Men-deploy proxy API menggunakan API

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Setiap organisasi memiliki siklus proses pengembangan software (SDLC) yang unik. Sering kali diperlukan untuk menyinkronkan dan menyelaraskan deployment proxy API dengan proses yang digunakan untuk layanan backend.

Metode Edge API yang ditunjukkan dalam topik ini dapat digunakan untuk mengintegrasikan pengelolaan proxy API ke dalam SDLC organisasi Anda. Penggunaan umum API ini adalah untuk menulis skrip atau kode yang men-deploy proxy API, atau yang memigrasikan proxy API dari satu lingkungan ke lingkungan lain, sebagai bagian dari proses otomatis yang lebih besar yang juga men-deploy atau memigrasikan aplikasi lain.

Edge API tidak membuat asumsi tentang SDLC Anda (atau SDLC orang lain). Sebaliknya, API ini mengekspos fungsi atomik yang dapat dikoordinasikan oleh tim pengembangan Anda untuk mengotomatiskan dan mengoptimalkan siklus proses pengembangan API Anda.

Untuk mengetahui informasi lengkapnya, lihat Edge API.

Untuk menggunakan Edge API, Anda harus mengautentikasi diri sendiri dalam panggilan Anda. Anda dapat melakukannya dengan salah satu metode berikut:

• OAuth2 (Khusus Public Cloud)
• SAML (Cloud Publik dan Pribadi)
• Autentikasi Dasar (tidak direkomendasikan; Cloud Publik dan Pribadi)

Topik ini berfokus pada kumpulan API yang digunakan untuk mengelola proxy API.

Video: Tonton video pendek ini untuk mempelajari cara men-deploy API.

Berinteraksi dengan API

Langkah-langkah berikut akan memandu Anda melakukan interaksi sederhana dengan API.

Mencantumkan API di organisasi Anda

Anda dapat memulai dengan mencantumkan semua proxy API di organisasi Anda. (Jangan lupa mengganti entri untuk EMAIL:PASSWORD dan ORG_NAME. Untuk mendapatkan petunjuk, lihat Menggunakan Edge API.

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

Contoh Respons:

[ "weatherapi" ]

Mendapatkan API

Anda dapat memanggil metode GET pada proxy API apa pun di organisasi Anda. Panggilan ini menampilkan daftar semua revisi proxy API yang tersedia.

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

Contoh Respons:

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

Satu-satunya detail yang ditampilkan oleh metode ini adalah nama proxy API beserta revisi terkait, yang memiliki nomor terkait. Proxy API terdiri dari paket file konfigurasi. Revisi menyediakan mekanisme ringan untuk mengelola update konfigurasi saat Anda melakukan iterasi. Revisi diberi nomor secara berurutan, sehingga Anda dapat mengembalikan perubahan dengan men-deploy revisi sebelumnya dari proxy API. Selain itu, Anda dapat men-deploy revisi proxy API ke lingkungan prod, sambil terus membuat revisi baru proxy API tersebut di lingkungan pengujian. Jika sudah siap, Anda dapat mempromosikan revisi yang lebih tinggi dari proxy API Anda dari lingkungan pengujian ke revisi sebelumnya dari proxy API di lingkungan produksi.

Dalam contoh ini, hanya ada satu revisi karena proxy API baru saja dibuat. Saat proxy API melewati siklus proses konfigurasi dan deployment iteratif, nomor revisi akan bertambah dengan bilangan bulat. Dengan menggunakan panggilan API langsung untuk men-deploy, Anda dapat secara opsional menaikkan nomor revisi proxy API. Terkadang saat membuat perubahan kecil, Anda mungkin tidak ingin menaikkan revisi.

Mendapatkan Revisi API

Versi API (misalnya, api.company.com/v1) jarang berubah. Saat Anda menaikkan versi API, hal ini menandakan kepada developer bahwa ada perubahan signifikan pada tanda tangan antarmuka eksternal yang diekspos oleh API.

Revisi proxy API adalah angka yang bertambah dan terkait dengan konfigurasi proxy API. Layanan API mempertahankan revisi konfigurasi Anda sehingga Anda dapat mengembalikan konfigurasi jika terjadi masalah. Secara default, revisi proxy API akan otomatis ditambah setiap kali Anda mengimpor proxy API menggunakan API Mengimpor proxy API. Jika Anda tidak ingin menambah revisi proxy API, gunakan API Perbarui revisi proxy API. Jika Anda menggunakan Maven untuk men-deploy, gunakan opsi clean atau update, seperti yang dijelaskan dalam readme plugin Maven.

Misalnya, Anda dapat memanggil metode GET pada revisi 1 proxy API untuk mendapatkan tampilan mendetail.

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

Contoh Respons

{
  "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"
}

Elemen konfigurasi proxy API ini didokumentasikan secara mendetail dalam referensi konfigurasi proxy API.

Men-deploy API ke lingkungan

Setelah proxy API dikonfigurasi untuk menerima dan meneruskan permintaan dengan benar, Anda dapat men-deploy-nya ke satu atau beberapa lingkungan. Biasanya, Anda melakukan iterasi pada proxy API di test, lalu, setelah siap, Anda mempromosikan revisi proxy API ke prod. Sering kali, Anda akan menemukan bahwa Anda memiliki lebih banyak revisi Proxy API di lingkungan pengujian, terutama karena Anda akan melakukan lebih sedikit iterasi di lingkungan produksi.

Proxy API tidak dapat dipanggil hingga di-deploy ke lingkungan. Setelah men-deploy revisi proxy API ke produksi, Anda dapat memublikasikan URL prod ke developer eksternal.

Cara mencantumkan lingkungan

Setiap organisasi di Apigee Edge memiliki setidaknya dua lingkungan: test dan prod. Perbedaan ini bersifat arbitrer. Tujuannya adalah memberi Anda area untuk memverifikasi bahwa proxy API Anda berfungsi dengan benar sebelum Anda membukanya untuk developer eksternal.

Setiap lingkungan hanyalah alamat jaringan, yang memungkinkan Anda memisahkan traffic antara proxy API yang sedang Anda kerjakan, dan proxy API yang diakses oleh aplikasi saat runtime.

Lingkungan juga menyediakan pemisahan data dan resource. Misalnya, Anda dapat menyiapkan cache yang berbeda dalam pengujian dan produksi, yang hanya dapat diakses oleh proxy API yang dijalankan di lingkungan tersebut.

Melihat lingkungan dalam organisasi

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

Contoh Respons

[ "test", "prod" ]

Menjelajahi deployment

Deployment adalah revisi proxy API yang telah di-deploy di lingkungan. Proxy API yang dalam status di-deploy dapat diakses melalui jaringan, di alamat yang ditentukan dalam elemen <VirtualHost> untuk lingkungan tersebut.

Men-deploy proxy API

Proxy API tidak dapat dipanggil hingga di-deploy. Layanan API mengekspos API RESTful yang memberikan kontrol atas proses deployment.

Hanya satu revisi proxy API yang dapat di-deploy di lingkungan pada waktu tertentu. Oleh karena itu, revisi yang di-deploy harus di-un-deploy. Anda dapat mengontrol apakah paket baru di-deploy sebagai revisi baru atau apakah paket tersebut menggantikan revisi yang ada.

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Batalkan deployment revisi yang ada terlebih dahulu. Tentukan nama lingkungan dan nomor revisi proxy API yang ingin Anda batalkan deployment-nya:

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

Kemudian, deploy revisi baru. Revisi baru proxy API harus sudah ada:

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

Deployment yang lancar (tanpa periode nonaktif)

Untuk meminimalkan potensi periode nonaktif selama deployment, gunakan parameter override pada metode deployment, dan tetapkan ke true.

Anda tidak dapat men-deploy satu revisi proxy API di atas revisi lainnya. Yang pertama harus selalu dibatalkan deployment-nya. Dengan menyetel override ke true, Anda menunjukkan bahwa satu revisi proxy API harus di-deploy melalui revisi yang saat ini di-deploy. Hasilnya, urutan deployment dibalik--revisi baru di-deploy, dan setelah deployment selesai, revisi yang sudah di-deploy akan di-undeploy.

Contoh berikut menetapkan nilai override dengan meneruskannya sebagai parameter formulir:

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

Anda dapat mengoptimalkan deployment lebih lanjut dengan menyetel parameter delay. Parameter delay menentukan interval waktu, dalam detik, sebelum revisi sebelumnya harus di-un-deploy. Efeknya adalah transaksi dalam proses memiliki interval waktu untuk diselesaikan sebelum proxy API yang memproses transaksi tersebut di-un-deploy. Berikut adalah yang terjadi dengan override=true dan parameter delay yang ditetapkan:

• Revisi 1 menangani permintaan.
• Revisi 2 sedang di-deploy secara paralel.
• Setelah Revisi 2 di-deploy sepenuhnya, traffic baru akan dikirim ke Revisi 2. Tidak ada traffic baru yang dikirim ke Revisi 1.
• Namun, Revisi 1 mungkin masih memproses transaksi yang ada. Dengan menetapkan parameter delay (misalnya, 15 detik), Anda memberi Revisi 1 waktu 15 detik untuk menyelesaikan pemrosesan transaksi yang ada.
• Setelah interval penundaan, Revisi 1 akan di-un-deploy.

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

Jika override=true digunakan bersama dengan delay, respons 5XX HTTP selama deployment dapat dihilangkan. Hal ini karena kedua revisi proxy API akan dideploy secara bersamaan, dengan revisi yang lebih lama di-undeploy setelah penundaan.

Melihat semua deployment Revisi API

Terkadang, Anda perlu mengambil daftar semua revisi proxy API yang saat ini di-deploy.

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"
}

Respons di atas berisi banyak properti khusus untuk infrastruktur internal Apigee Edge. Kecuali jika Anda menggunakan Apigee Edge on-premise, Anda tidak dapat mengubah setelan ini.

Properti penting yang ada dalam respons adalah organization, environment, aPIProxy, name, dan state. Dengan meninjau nilai properti ini, Anda dapat mengonfirmasi bahwa revisi tertentu dari proxy API di-deploy di lingkungan.

Melihat semua deployment di lingkungan pengujian

Anda juga dapat mengambil status deployment untuk lingkungan tertentu (termasuk nomor revisi proxy API yang saat ini di-deploy) menggunakan panggilan berikut:

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

Tindakan ini akan menampilkan hasil yang sama seperti di atas untuk setiap API yang di-deploy di lingkungan pengujian

Melihat semua deployment di organisasi Anda

Untuk mengambil daftar semua revisi yang saat ini di-deploy dari semua proxy API di semua lingkungan, gunakan metode API berikut:

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

Tindakan ini akan menampilkan hasil yang sama seperti di atas untuk semua proxy API yang di-deploy di semua lingkungan.

Karena API bersifat RESTful, Anda cukup menggunakan metode POST, beserta payload JSON atau XML, terhadap resource yang sama untuk membuat proxy API.

Profil untuk proxy API Anda dibuat. Representasi default proxy API adalah dalam JavaScript object notation (JSON). Di bawah ini adalah respons JSON default untuk permintaan POST di atas, yang membuat proxy API bernama weatherapi. Deskripsi setiap elemen dalam profil adalah sebagai berikut:

{
  "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"
}

Profil proxy API yang dibuat menunjukkan struktur lengkap proxy API:

• APIProxy revision: Iterasi konfigurasi proxy API yang diberi nomor secara berurutan, sebagaimana dikelola oleh Layanan API
• APIProxy name: Nama unik proxy API
• ConfigurationVersion: Versi Layanan API yang sesuai dengan konfigurasi proxy API
• CreatedAt: Waktu saat proxy API dibuat, diformat dalam waktu UNIX
• CreatedBy: Alamat email pengguna Apigee Edge yang membuat proxy API
• DisplayName: Nama proxy API yang mudah digunakan
• LastModifiedAt: Waktu saat proxy API dibuat, diformat dalam waktu UNIX
• LastModifiedBy: Alamat email pengguna Apigee Edge yang membuat proxy API
• Policies: Daftar kebijakan yang telah ditambahkan ke proxy API ini
• ProxyEndpoints: Daftar ProxyEndpoint bernama
• Resources: Daftar resource (JavaScript, Python, Java, XSLT) yang tersedia untuk dieksekusi di proxy API ini
• TargetServers: Daftar TargetServer bernama (yang dapat dibuat menggunakan Management API), yang digunakan dalam konfigurasi lanjutan untuk tujuan load balancing
• TargetEndpoints: Daftar TargetEndpoint bernama

Perhatikan bahwa banyak elemen konfigurasi proxy API yang dibuat menggunakan metode POST sederhana di atas kosong. Dalam topik berikut, Anda akan mempelajari cara menambahkan dan mengonfigurasi komponen utama proxy API.

Anda juga dapat membaca elemen konfigurasi ini di referensi konfigurasi proxy API.

Membuat skrip terhadap API

Menggunakan proxy API contoh, yang tersedia di GitHub, menyediakan skrip shell yang membungkus alat deployment Apigee. Jika karena alasan tertentu Anda tidak dapat menggunakan alat deployment Python, Anda dapat memanggil API secara langsung. Kedua pendekatan tersebut ditunjukkan dalam contoh skrip di bawah.

Membungkus alat deployment

Pertama, pastikan alat deployment Python tersedia di lingkungan lokal Anda.

Kemudian, buat file untuk menyimpan kredensial Anda. Skrip deployment yang Anda tulis akan mengimpor setelan ini, sehingga membantu Anda mengelola kredensial untuk akun Anda secara terpusat. Dalam contoh Platform API, file ini disebut setenv.sh.

#!/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

File di atas membuat semua setelan Anda tersedia untuk skrip shell yang membungkus alat deploy.

Sekarang buat skrip shell yang mengimpor setelan tersebut dan menggunakannya untuk memanggil alat deployment. (Untuk contoh, lihat Contoh platform API Apigee.)

#!/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

Untuk mempermudah hidup Anda, buat juga skrip untuk memanggil dan menguji API, sebagai berikut:

#!/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}"

Memanggil API secara langsung

Anda dapat menulis skrip shell sederhana yang mengotomatiskan proses upload dan men-deploy proxy API.

Skrip di bawah ini memanggil Management API secara langsung. Tindakan ini akan membatalkan deployment revisi Proxy API yang sedang Anda update, membuat file ZIP dari direktori /apiproxy yang berisi file konfigurasi proxy Anda, lalu mengupload, mengimpor, dan men-deploy konfigurasi tersebut.

#!/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