API'yi kullanarak API proxy'leri dağıtma

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Her kuruluşun benzersiz bir yazılım geliştirme yaşam döngüsü (SDLC) vardır. API proxy dağıtımının, arka uç hizmetleri için kullanılan süreçlerle senkronize edilmesi ve uyumlu hale getirilmesi genellikle gerekir.

Bu konuda gösterilen Edge API yöntemleri, API proxy yönetimini kuruluşunuzun SDLC'sine entegre etmek için kullanılabilir. Bu API'nin yaygın bir kullanımı, API proxy'lerini dağıtan veya API proxy'lerini bir ortamdan diğerine taşıyan komut dosyaları ya da kodlar yazmaktır. Bu komut dosyaları veya kodlar, diğer uygulamaları da dağıtan ya da taşıyan daha büyük bir otomatik sürecin parçasıdır.

Edge API, SDLC'niz (veya başka birinin) hakkında hiçbir varsayımda bulunmaz. Bunun yerine, API geliştirme yaşam döngünüzü otomatikleştirmek ve optimize etmek için geliştirme ekibiniz tarafından koordine edilebilecek atomik işlevler sunar.

Eksiksiz bilgi için Edge API'leri başlıklı makaleyi inceleyin.

Edge API'yi kullanmak için çağrılarınızda kimliğinizi doğrulamanız gerekir. Bu işlemi aşağıdaki yöntemlerden biriyle yapabilirsiniz:

Bu konuda, API proxy'lerini yönetmeye yönelik API'ler üzerinde durulmaktadır.

Video: API'yi nasıl dağıtacağınızı öğrenmek için bu kısa videoyu izleyin.

API ile etkileşim

Aşağıdaki adımlar, API'lerle basit etkileşimler kurma konusunda size yol gösterir.

Kuruluşunuzdaki API'leri listeleme

Kuruluşunuzdaki tüm API proxy'lerini listeleyerek başlayabilirsiniz. (EMAIL:PASSWORD ve ORG_NAME girişlerini değiştirmeyi unutmayın. Talimatlar için Edge API'yi kullanma başlıklı makaleyi inceleyin.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Örnek Yanıt:

[ "weatherapi" ]

API alma

Kuruluşunuzdaki herhangi bir API proxy'sinde GET yöntemini çağırabilirsiniz. Bu çağrı, API proxy'sinin mevcut tüm revizyonlarının listesini döndürür.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Örnek Yanıt:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

Bu yöntem tarafından döndürülen tek ayrıntı, API proxy'sinin adı ve ilişkili revizyonudur. Revizyonun ilişkili bir numarası vardır. API proxy'leri, bir yapılandırma dosyası paketinden oluşur. Düzeltmeler, yineleme yaparken yapılandırmadaki güncellemelerinizi yönetmek için basit bir mekanizma sağlar. Revizyonlar sıralı olarak numaralandırılır. Bu sayede, API proxy'nizin önceki bir revizyonunu dağıtarak değişikliği geri alabilirsiniz. Ayrıca, bir API proxy'sinin düzeltmesini üretim ortamına dağıtabilir ve bu API proxy'sinin yeni düzeltmelerini test ortamında oluşturmaya devam edebilirsiniz. Hazır olduğunuzda, API proxy'nizin test ortamındaki daha yüksek düzeltmesini, üretim ortamındaki API proxy'nin önceki düzeltmesi üzerinde yükseltebilirsiniz.

Bu örnekte, API proxy'si yeni oluşturulduğu için yalnızca bir revizyon vardır. Bir API proxy'si, yinelemeli yapılandırma ve dağıtım yaşam döngüsünde ilerledikçe düzeltme numarası tam sayılarla artar. Dağıtım için doğrudan API çağrılarını kullanırken API proxy'sinin revizyon numarasını isteğe bağlı olarak artırabilirsiniz. Bazen küçük değişiklikler yaptığınızda revizyonu artırmak istemeyebilirsiniz.

API Düzeltmesini Alma

API sürümü (örneğin, api.company.com/v1) çok nadiren değişmelidir. API sürümünü artırdığınızda, geliştiricilere API tarafından sunulan harici arayüzün imzasında önemli bir değişiklik yapıldığı bildirilir.

API proxy'si revizyonu, bir API proxy'si yapılandırmasıyla ilişkili artırılmış bir sayıdır. API Hizmetleri, yapılandırmalarınızın düzeltmelerini saklar. Böylece bir sorun olduğunda yapılandırmayı geri alabilirsiniz. Varsayılan olarak, bir API proxy'sinin revizyonu, API proxy'si içe aktarma API'si kullanılarak bir API proxy'si her içe aktarıldığında otomatik olarak artırılır. Bir API proxy'sinin düzeltmesini artırmak istemiyorsanız API proxy düzeltmesini güncelleme API'sini kullanın. Dağıtım için Maven kullanıyorsanız Maven eklentisiyle ilgili readme dosyasında açıklandığı gibi clean veya update seçeneklerini kullanın.

Örneğin, ayrıntılı bir görünüm elde etmek için API proxy revizyonu 1'de GET yöntemini çağırabilirsiniz.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Örnek Yanıt

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Bu API proxy'si yapılandırma öğeleri, API proxy'si yapılandırma referansında ayrıntılı olarak açıklanmıştır.

Bir ortama API dağıtma

API proxy'niz istekleri düzgün şekilde alıp yönlendirecek şekilde yapılandırıldıktan sonra bunu bir veya daha fazla ortama dağıtabilirsiniz. Genellikle API proxy'lerini test içinde yineleyip hazır olduğunda API proxy düzeltmesini prod'ye yükseltirsiniz. Genellikle, test ortamında bir API proxy'sinin çok daha fazla düzeltmesinin olduğunu görürsünüz. Bunun temel nedeni, üretim ortamında çok daha az yineleme yapmanızdır.

Bir API proxy'si bir ortama dağıtılana kadar çağrılamaz. API proxy düzeltmesini üretime dağıttıktan sonra prod URL'yi harici geliştiricilerle paylaşabilirsiniz.

Ortamları listeleme

Apigee Edge'deki her kuruluşun en az iki ortamı vardır: test ve prod. Bu ayrım keyfidir. Amaç, API proxy'nizi harici geliştiricilere açmadan önce düzgün çalıştığını doğrulayabileceğiniz bir alan sağlamaktır.

Her ortam aslında yalnızca bir ağ adresidir. Bu sayede, üzerinde çalıştığınız API proxy'leri ile uygulamalar tarafından çalışma zamanında erişilen API proxy'leri arasındaki trafiği ayırabilirsiniz.

Ortamlar, verilerin ve kaynakların ayrılmasını da sağlar. Örneğin, test ve üretim ortamlarında yalnızca o ortamda yürütülen API proxy'leri tarafından erişilebilen farklı önbellekler oluşturabilirsiniz.

Kuruluşlardaki ortamları görüntüleme

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Örnek Yanıt

[ "test", "prod" ]

Dağıtımları keşfetme

Dağıtım, bir ortamda dağıtılmış bir API proxy'sinin düzeltmesidir. Dağıtılmış durumdaki bir API proxy'sine, ağ üzerinden erişilebilir. Bu proxy'ye erişmek için ilgili ortamın <VirtualHost> öğesinde tanımlanan adresler kullanılır.

API proxy'si dağıtma

API proxy'leri, dağıtılana kadar çağrılamaz. API Hizmetleri, dağıtım süreci üzerinde kontrol sağlayan RESTful API'ler sunar.

Bir ortamda belirli bir zamanda yalnızca bir API proxy'sinin düzeltmesi dağıtılabilir. Bu nedenle, dağıtılan düzeltmenin dağıtımı geri alınmalıdır. Yeni paketin yeni bir düzeltme olarak mı dağıtılacağını yoksa mevcut düzeltmenin üzerine mi yazılacağını kontrol edebilirsiniz.

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Öncelikle mevcut düzeltmenin dağıtımını kaldırın. Kaldırmak istediğiniz API proxy'sinin ortam adını ve düzeltme numarasını belirtin:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Ardından yeni düzeltmeyi dağıtın. API proxy'sinin yeni düzeltmesi zaten mevcut olmalıdır: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Sorunsuz dağıtım (sıfır kesinti)

Dağıtım sırasında olası kapalı kalma süresini en aza indirmek için dağıtım yönteminde override parametresini kullanın ve true olarak ayarlayın.

Bir API proxy'sinin bir düzeltmesini diğerinin üzerine dağıtamazsınız. Birincisi her zaman dağıtılmamış olmalıdır. override değerini true olarak ayarlayarak bir API proxy'sinin bir düzeltmesinin, şu anda dağıtılan düzeltme üzerinden dağıtılması gerektiğini belirtirsiniz. Sonuç olarak, dağıtım sırası tersine çevrilir. Yeni düzeltme dağıtılır ve dağıtım tamamlandıktan sonra önceden dağıtılmış düzeltmenin dağıtımı kaldırılır.

Aşağıdaki örnekte, override değeri bir form parametresi olarak iletilerek ayarlanır: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

delay parametresini ayarlayarak dağıtımı daha da optimize edebilirsiniz. delay parametresi, önceki düzeltmenin devre dışı bırakılacağı süreyi saniye cinsinden belirtir. Bu durumda, API proxy'si tarafından işlenen işlemlerin dağıtımı kaldırılmadan önce devam eden işlemlerin tamamlanması için bir zaman aralığı belirlenir. Aşağıda, override=true ve delay parametre grubuyla ilgili işlemler açıklanmaktadır:

  • 1. düzeltme, istekleri işliyor.
  • 2. düzeltme paralel olarak dağıtılıyor.
  • 2. düzeltme tamamen dağıtıldığında yeni trafik 2. düzeltmeye gönderilir. 1. düzeltmeye yeni trafik gönderilmez.
  • Ancak 1. sürüm, mevcut işlemleri işlemeye devam ediyor olabilir. delay parametresini (örneğin, 15 saniye) ayarlayarak 1. düzeltmeye mevcut işlemleri tamamlaması için 15 saniye süre tanırsınız.
  • Gecikme aralığından sonra 1. Düzeltme'nin dağıtımı kaldırılır.
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Sorgu Parametresi Açıklama
override

Varsayılan değer false'dır (normal dağıtım davranışı: mevcut düzeltmenin dağıtımı kaldırılır, ardından yeni düzeltme dağıtılır).

Normal dağıtım davranışını geçersiz kılmak ve sorunsuz dağıtım sağlamak için true olarak ayarlayın. Yeni düzeltme dağıtılırken mevcut düzeltme dağıtılmaya devam eder. Yeni düzeltme dağıtıldığında eski düzeltmenin dağıtımı kaldırılır. Kaldırma işleminin ne zaman gerçekleşeceğini kontrol etmek için delay parametresiyle birlikte kullanın.
delay

İşlemeyi, mevcut düzeltme dağıtımı kaldırılmadan önce tamamlamak ve 502 Bad Gateway veya 504 Gateway Timeout errors olasılığını ortadan kaldırmak için bu parametreyi, dağıtımın kaldırılmasının geciktirilmesini istediğiniz saniye sayısına ayarlayın. Ayarlayabileceğiniz saniye sayısı sınırlı değildir ve yüksek bir saniye sayısı ayarlamanın performans üzerinde olumsuz bir etkisi yoktur. Gecikme sırasında eski düzeltmeye yeni trafik gönderilmez.

Varsayılan değer 0 saniyedir. override doğru olarak ayarlandığında ve delay 0 olduğunda, yeni düzeltme dağıtıldıktan hemen sonra mevcut düzeltmenin dağıtımı kaldırılır. Negatif değerler 0 (sıfır) saniye olarak kabul edilir.

override=true, delay ile birlikte kullanıldığında dağıtım sırasında HTTP 5XX yanıtları ortadan kaldırılabilir. Bunun nedeni, her iki API proxy düzeltmesinin de aynı anda dağıtılması ve eski düzeltmenin gecikmeden sonra dağıtımının kaldırılmasıdır.

Bir API revizyonunun tüm dağıtımlarını görme

Bazen bir API proxy'sinin şu anda dağıtılan tüm revizyonlarının listesini getirmek gerekir.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

Yukarıdaki yanıtta, Apigee Edge'in dahili altyapısına özgü birçok özellik yer alıyor. Apigee Edge şirket içi sürümünü kullanmıyorsanız bu ayarları değiştiremezsiniz.

Yanıtın içerdiği önemli özellikler organization, environment, aPIProxy, name ve state'dir. Bu mülk değerlerini inceleyerek bir API proxy'sinin belirli bir revizyonunun bir ortama dağıtıldığını doğrulayabilirsiniz.

Test ortamındaki tüm dağıtımları görme

Ayrıca, aşağıdaki çağrıyı kullanarak belirli bir ortamın dağıtım durumunu (şu anda dağıtılan API proxy'sinin düzeltme numarası dahil) da alabilirsiniz:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Bu, test ortamında dağıtılan her API için yukarıdakiyle aynı sonucu döndürür.

Kuruluşunuzdaki tüm dağıtımları görme

Tüm ortamlardaki tüm API proxy'lerinin şu anda dağıtılmış olan tüm revizyonlarının listesini getirmek için aşağıdaki API yöntemini kullanın:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Bu, tüm ortamlarda dağıtılan tüm API proxy'leri için yukarıdakiyle aynı sonucu döndürür.

API RESTful olduğundan, API proxy'si oluşturmak için aynı kaynağa karşı JSON veya XML yüküyle birlikte POST yöntemini kullanmanız yeterlidir.

API proxy'niz için bir profil oluşturulur. API proxy'sinin varsayılan gösterimi JavaScript Object Notation (JSON) biçimindedir. Aşağıda, weatherapi adlı bir API proxy'si oluşturan yukarıdaki POST isteğine verilen varsayılan JSON yanıtı yer almaktadır. Profildeki her bir öğenin açıklaması aşağıda verilmiştir:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Oluşturulan API proxy profili, API proxy'sinin yapısının tamamını gösterir:

  • APIProxy revision: API Hizmetleri tarafından tutulan API proxy'si yapılandırmasının sıralı numaralandırılmış yinelemesi
  • APIProxy name: API proxy'sinin benzersiz adı
  • ConfigurationVersion: API proxy'si yapılandırmasının uyduğu API Hizmetleri sürümü
  • CreatedAt: API proxy'sinin oluşturulduğu zaman (UNIX zamanı biçiminde)
  • CreatedBy: API proxy'sini oluşturan Apigee Edge kullanıcısının e-posta adresi
  • DisplayName: API proxy'si için kullanıcı dostu bir ad
  • LastModifiedAt: API proxy'sinin oluşturulduğu zaman, UNIX zamanı biçiminde
  • LastModifiedBy: API proxy'sini oluşturan Apigee Edge kullanıcısının e-posta adresi
  • Policies: Bu API proxy'sine eklenen politikaların listesi
  • ProxyEndpoints: Adlandırılmış ProxyEndpoint'lerin listesi
  • Resources: Bu API proxy'sinde yürütülebilen kaynakların (JavaScript, Python, Java, XSLT) listesi
  • TargetServers: Yük dengeleme amacıyla gelişmiş yapılandırmalarda kullanılan, adlandırılmış TargetServer'ların (yönetim API'si kullanılarak oluşturulabilir) listesi
  • TargetEndpoints: Adlandırılmış TargetEndpoint'lerin listesi

Yukarıdaki basit POST yöntemiyle oluşturulan API proxy yapılandırmasının birçok öğesinin boş olduğunu unutmayın. Aşağıdaki konularda, bir API proxy'sinin temel bileşenlerini nasıl ekleyeceğinizi ve yapılandıracağınızı öğreneceksiniz.

Bu yapılandırma öğeleri hakkında API proxy'si yapılandırma referansından da bilgi edinebilirsiniz.

API'ye karşı komut dosyası oluşturma

GitHub'da bulunan Örnek API proxy'lerini kullanma, Apigee dağıtım aracını sarmalayan kabuk komut dosyaları sağlar. Herhangi bir nedenle Python dağıtım aracını kullanamıyorsanız API'yi doğrudan çağırabilirsiniz. Her iki yaklaşım da aşağıdaki örnek komut dosyalarında gösterilmektedir.

Dağıtım aracını sarmalama

Öncelikle, Python dağıtım aracının yerel ortamınızda kullanılabilir olduğundan emin olun.

Ardından, kimlik bilgilerinizi saklayacak bir dosya oluşturun. Yazdığınız dağıtım komut dosyaları bu ayarları içe aktarır. Böylece, hesabınızın kimlik bilgilerini merkezi olarak yönetebilirsiniz. API Platformu örneğinde bu dosyanın adı setenv.sh'dir.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

Yukarıdaki dosya, dağıtım aracını sarmalayan kabuk komut dosyalarında tüm ayarlarınızı kullanılabilir hale getirir.

Şimdi bu ayarları içe aktaran ve dağıtım aracını çağırmak için kullanan bir kabuk komut dosyası oluşturun. (Örnek için Apigee API platform örnekleri konusuna bakın.)

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

Hayatınızı kolaylaştırmak için API'yi çağırmak ve test etmek üzere aşağıdaki gibi bir komut dosyası da oluşturun:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

API'yi doğrudan çağırma

API proxy'lerini yükleme ve dağıtma sürecini otomatikleştiren basit kabuk komut dosyaları yazmak faydalı olabilir.

Aşağıdaki komut dosyası, Management API'yi doğrudan çağırır. Güncellediğiniz API proxy'sinin mevcut sürümünün dağıtımını kaldırır, proxy yapılandırma dosyalarınızı içeren /apiproxy dizininden bir ZIP dosyası oluşturur ve ardından yapılandırmayı yükler, içe aktarır ve dağıtır.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST