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 işlemlerle senkronize edilmesi ve uyumlu hale getirilmesi genellikle gereklidir.

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 alanı, API proxy'leri dağıtan ya da API proxy'lerini bir ortamdan diğerine taşıyan komut dosyaları veya kod yazmaktır. Bu, aynı zamanda başka uygulamaları dağıtan ya da taşıyan daha büyük otomatik bir sürecin parçası olur.

Edge API, SDLC'niz (veya başka bir kişinin SDLC'si) hakkında herhangi bir varsayımda bulunmaz. Aksine, API geliştirme yaşam döngünüzü otomatikleştirmek ve optimize etmek için geliştirme ekibiniz tarafından koordine edilebilecek atom işlevleri sunar.

Tüm bilgiler için Edge API'leri sayfasına göz atın.

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

  • OAuth2 (yalnızca herkese açık bulut)
  • SAML (Public ve Private Cloud)
  • Basic Auth (önerilmez; Herkese Açık ve Private Cloud)

Bu konu, API proxy'lerini yönetmek için kullanılan API'lere odaklanır.

Video: API'leri nasıl dağıtacağınızı öğrenmek için bu kısa videoya göz atın.

API ile etkileşimde bulunma

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

Kuruluşunuzdaki API'leri listeleme

Kuruluşunuzdaki tüm API proxy'lerini listeleyerek başlayabilirsiniz. (Girişleri EMAIL:PASSWORD ve ORG_NAME yerine değiştirmeyi unutmayın. Talimatlar için Edge API'sini kullanma başlıklı makaleye bakın.

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

Örnek Yanıt:

[ "weatherapi" ]

API alın

GET yöntemini kuruluşunuzdaki herhangi bir API proxy'sinde çağırabilirsiniz. Bu çağrı, API proxy'sinin kullanılabilir tüm düzeltmelerinin 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öntemin döndürdüğü tek ayrıntı, API proxy'sinin adı ve ilişkili bir numaraya sahip olan ilişkili düzeltmenin adıdır. API proxy'leri bir yapılandırma dosyası paketinden oluşur. Düzeltmeler, siz yineleme sırasında yapılandırma güncellemelerinizi yönetmek için basit bir mekanizma sağlar. Düzeltmeler sıralı bir şekilde numaralandırılır. Böylece API proxy'nizin önceki bir düzeltmesini dağıtarak değişikliği geri alabilirsiniz. Ayrıca, test ortamında API proxy'sinin yeni düzeltmelerini oluşturmaya devam ederken üretim ortamına bir API proxy'sinin düzeltmesini dağıtabilirsiniz. Hazır olduğunuzda, üretim ortamında API proxy'sinin önceki düzeltmesi üzerinden API proxy'nizin daha yüksek düzeltme sürümünü test ortamından tanıtabilirsiniz.

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

API Düzeltmesi Alma

API sürümü (örneğin, api.company.com/v1) çok nadir değişir. API sürümünü artırmak, geliştiricilere API tarafından gösterilen harici arayüzün imzasında önemli bir değişiklik olduğunu gösterir.

API proxy'si düzeltmesi, API proxy yapılandırmasıyla ilişkili artımlı bir sayıdır. API Hizmetleri, yapılandırmalarınız üzerinde düzeltmeler yapar. Böylece bir sorun olduğunda yapılandırmayı geri alabilirsiniz. Varsayılan olarak, API proxy'sini içe aktarma API'si kullanılarak bir API proxy'sini içe aktardığınız her seferde API proxy'sinin düzeltmesi otomatik olarak artar. Bir API proxy'sinin düzeltmesini artırmak istemiyorsanız API proxy düzeltmesini güncelle API'sini kullanın. Dağıtım için Maven kullanıyorsanız Maven eklentisi readme bölümünde açıklandığı gibi clean veya update seçeneklerini kullanın.

Örneğin, ayrıntılı görünüm elde etmek için API proxy düzeltmesi 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 yapılandırması referansı bölümünde ayrıntılı olarak açıklanmıştır.

API'leri bir ortama dağıtma

API proxy'niz istekleri düzgün şekilde alacak ve yönlendirecek şekilde yapılandırıldıktan sonra bir veya daha fazla ortama dağıtabilirsiniz. Genellikle test içindeki API proxy'lerinde iterasyonlar yaparsınız ve hazır olduğunuzda API proxy düzeltmesini prod diline tanıtırsınız. Çoğunlukla test ortamında API proxy'sinin çok daha fazla düzeltmesine sahip olduğunuzu görürsünüz. Bunun başlıca nedeni, üretim ortamında çok daha az iterasyon yapmanızdır.

API proxy'si, bir ortama dağıtılana kadar çağrılamaz. API proxy düzeltmesini üretim için dağıttıktan sonra prod URL'sini harici geliştiricilere yayınlayabilirsiniz.

Ortamları listeleme

Apigee Edge'deki her kuruluş test ve prod olmak üzere en az iki ortama sahiptir. Bu fark rastgeledir. Buradaki amaç, API proxy'nizi harici geliştiricilere açmadan önce düzgün çalıştığını doğrulayabileceğiniz bir alan sunmaktır.

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

Ortamlar ayrıca veri ve kaynakların ayrıştırılmasını da sağlar. Örneğin, test ve üretim aşamasında farklı önbellekler oluşturabilirsiniz. Bunlara, yalnızca ilgili ortamda çalışan API proxy'leri tarafından erişilebilir.

Kuruluştaki 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ılan bir API proxy'sinin düzeltmesidir. Dağıtıldı durumundaki bir API proxy'sine, söz konusu ortamın <VirtualHost> öğesinde tanımlanan adreslerden ağ üzerinden erişilebilir.

API proxy'si dağıtma

Dağıtılana kadar API proxy'leri çağrılamaz. API Hizmetleri, dağıtım süreci üzerinde kontrol sahibi olan RESTful API'leri kullanıma sunar.

Bir ortama aynı anda API proxy'sinin yalnızca bir düzeltmesi dağıtılabilir. Bu nedenle, dağıtılan düzeltmenin dağıtımı kaldırılmalıdır. Yeni paketin yeni bir düzeltme olarak dağıtılıp dağıtılmayacağını veya mevcut düzeltmenin üzerine yazıp yazmayacağını kontrol edebilirsiniz.

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

Önce mevcut düzeltmenin dağıtımını kaldırın. Dağıtımı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 halihazırda 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 kapalı kalma süresi)

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

Bir API proxy'sinin bir düzeltmesini diğerinin üzerine dağıtamazsınız. İlkinin dağıtımı her zaman kaldırılmalı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. Bunun sonucunda dağıtım sırası tersine çevrilir. Yeni düzeltme dağıtılır ve dağıtım tamamlandığında, önceden dağıtılmış olan düzeltmenin dağıtımı kaldırılır.

Aşağıdaki örnekte override değeri, bir form parametresi olarak iletilerek ayarlanmaktadı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 dağıtımının kaldırılmasından önce saniye cinsinden bir zaman aralığı belirtir. Bunun nedeni, yayındaki işlemlerde, API proxy'si tarafından yapılan işlemlerin dağıtılmadan önce tamamlanması gereken bir zaman aralığı bulunmasıdır. override=true ve delay parametre grubunda şunlar gerçekleşir:

  • Düzeltme 1, istekleri ele alıyor.
  • Düzeltme 2 paralel olarak dağıtılıyor.
  • Düzeltme 2 tam olarak dağıtıldığında yeni trafik Düzeltme 2'ye gönderilir. Düzeltme 1'e yeni trafik gönderilmez.
  • Ancak Düzeltme 1, mevcut işlemleri işlemeye devam ediyor olabilir. delay parametresini (örneğin, 15 saniye) ayarlayarak Düzeltme 1'e mevcut işlemlerin işlenmesini tamamlaması için 15 saniye süre tanırsınız.
  • Gecikme aralığından sonra Düzeltme 1'in 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'dir (normal dağıtım davranışı: Mevcut düzeltmenin dağıtımı kaldırılır ve 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 değerine ayarlayın. Yeni düzeltme de 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. Dağıtımın kaldırılacağı zamanı kontrol etmek için delay parametresiyle birlikte kullanın.
delay

Dağıtım kaldırılmadan önce mevcut düzeltmede işlemin tamamlanmasını sağlamak 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ı istediğiniz saniye sayısına ayarlayın. Ayarlayabileceğiniz saniye sayısıyla ilgili bir sınır ve yüksek saniye değerini ayarlamanın performans üzerinde herhangi bir etkisi yoktur. Gecikme sırasında eski düzeltmeye yeni trafik gönderilmez.

Varsayılan değer 0 (sıfır) saniyedir. override değeri doğru değerine ve delay değeri 0 olduğunda mevcut düzeltmenin dağıtımı, yeni düzeltme dağıtıldıktan hemen sonra 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ı 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ılmasıdır.

Bir API Düzeltmesinin tüm dağıtımlarını görün

Bazen bir API proxy'sinin halihazırda dağıtılan tüm düzeltmelerinin 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 özel birçok özellik yer almaktadır. Şirket içinde Apigee Edge kullanmıyorsanız bu ayarları değiştiremezsiniz.

Yanıtta bulunan önemli özellikler organization, environment, aPIProxy, name ve state'dir. Bu özellik değerlerini inceleyerek API proxy'sinin belirli bir düzeltmesinin ortamda dağıtıldığını onaylayabilirsiniz.

Test ortamında tüm dağıtımları göster

Aşağıdaki çağrıyı kullanarak belirli bir ortam için dağıtım durumunu da (şu anda dağıtılan API proxy'sinin düzeltme numarası dahil) 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ıdaki sonucun aynısını döndürür

Kuruluşunuzdaki tüm dağıtımları inceleyin

Tüm ortamlarda tüm API proxy'lerinin hâlihazırda dağıtılmış olan tüm düzeltmelerinin 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ı kaynakta POST yöntemini bir JSON veya XML yüküyle birlikte kullanabilirsiniz.

API proxy'niz için bir profil oluşturulur. API proxy'sinin varsayılan temsili, JavaScript nesne gösterimi (JSON) şeklindedir. Aşağıda, weatherapi adlı bir API proxy'si oluşturan yukarıdaki POST isteğine verilen varsayılan JSON yanıtı bulunmaktadır. Profildeki her bir öğenin açıklaması şu şekildedir:

{
  "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 tüm yapısını gösterir:

  • APIProxy revision: API proxy yapılandırmasının API Hizmetleri tarafından korunan sıralı numaralandırılmış iterasyonu
  • APIProxy name: API proxy'sinin benzersiz adı
  • ConfigurationVersion: API proxy yapılandırmasının uygun olduğu API Hizmetleri sürümü
  • CreatedAt: API proxy'sinin oluşturulduğu saat (UNIX olarak biçimlendirilir)
  • 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 olarak biçimlendirilir)
  • 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ış ProxyEndpoints listesi
  • Resources: Bu API proxy'sinde yürütülebilecek kaynakların listesi (JavaScript, Python, Java, XSLT)
  • TargetServers: Yük dengeleme amacıyla gelişmiş yapılandırmalarda kullanılan, adlandırılmış TargetServer'ların listesi (yönetim API'si kullanılarak oluşturulabilir)
  • TargetEndpoints: Adlandırılmış TargetEndpoints listesi

Yukarıdaki basit POST yöntemi kullanılarak oluşturulan API proxy yapılandırması öğelerinin çoğunun 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 bilgi edinmek için API proxy yapılandırma referansını da inceleyebilirsiniz.

API'ye yönelik komut dosyası çalıştırma

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

Dağıtım aracını sarmalama

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

Ardından kimlik bilgilerinizin saklanacağı bir dosya oluşturun. Yazdığınız dağıtım komut dosyaları bu ayarları içe aktararak hesabınızın kimlik bilgilerini merkezi olarak yönetmenize yardımcı olur. API Platformu örneğinde bu dosya setenv.sh olarak adlandırılır.

#!/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, tüm ayarlarınızı, dağıtım aracını sarmalayan kabuk komut dosyaları tarafından kullanılabilmesini sağlar.

Şimdi bu ayarları içe aktaran ve bunları dağıtım aracını çağırmak için kullanan bir kabuk komut dosyası oluşturun. (Örnek için Apigee API platform örnekleri sayfasına göz atı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ı gerçekten kolaylaştırmak için aşağıdaki gibi API'yi çağırıp test edecek 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 işlemini otomatikleştiren basit kabuk komut dosyaları yazmak yararlı olabilir.

Aşağıdaki komut dosyası, Management API'yi doğrudan çağırır. Güncellemekte olduğunuz API proxy'sinin mevcut düzeltmesinin dağıtımını kaldırır, /apiproxy dizininden proxy yapılandırma dosyalarınızı içeren bir ZIP dosyası oluşturur, 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