Men-deploy proxy API menggunakan API

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

Setiap organisasi memiliki software development lifecycle (SDLC) yang unik. Sering kali Anda perlu menyinkronkan dan menyelaraskan deployment proxy API dengan proses yang digunakan untuk layanan backend.

Metode Edge API yang didemonstrasikan 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 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 orang lain, dalam hal ini). Sebaliknya, versi ini menampilkan fungsi atomik yang dapat dikoordinasikan oleh tim pengembangan untuk mengotomatiskan dan mengoptimalkan siklus proses pengembangan API Anda.

Untuk mengetahui informasi selengkapnya, 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 Cloud Publik)
  • SAML (Cloud Publik dan Pribadi)
  • Basic Auth (tidak direkomendasikan; Public dan Private Cloud)

Topik ini berfokus pada serangkaian API yang ditujukan untuk mengelola proxy API.

Video: Tonton video singkat 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 dengan 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 memberikan mekanisme ringan untuk mengelola pembaruan konfigurasi saat Anda melakukan iterasi. Revisi diberi nomor secara urut, sehingga Anda dapat mengembalikan perubahan dengan men-deploy revisi proxy API sebelumnya. Selain itu, Anda dapat men-deploy revisi proxy API ke lingkungan produksi, sambil terus membuat revisi baru proxy API tersebut di lingkungan pengujian. Jika sudah siap, Anda dapat mempromosikan revisi proxy API yang lebih tinggi dari lingkungan pengujian, dibandingkan revisi proxy API sebelumnya di lingkungan produksi.

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

Mendapatkan Revisi API

Versi API (misalnya, api.company.com/v1) akan jarang berubah. Jika versi API dinaikkan, ini akan memberi tahu developer bahwa tanda tangan antarmuka eksternal terekspos oleh API mengalami perubahan signifikan.

Revisi proxy API adalah pertambahan angka yang terkait dengan konfigurasi proxy API. Layanan API mempertahankan revisi konfigurasi sehingga Anda dapat mengembalikan konfigurasi jika terjadi masalah. Secara default, revisi proxy API secara otomatis bertambah setiap kali Anda mengimpor proxy API menggunakan API Import an API proxy. Jika Anda tidak ingin menambah revisi proxy API, gunakan Update proxy proxy API untuk memperbarui 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 proxy API revisi 1 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 proxy API di test, lalu jika sudah siap, Anda mempromosikan revisi proxy API menjadi 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 sebelum di-deploy ke lingkungan. Setelah men-deploy revisi proxy API ke produksi, Anda dapat memublikasikan URL prod ke developer eksternal.

Cara menampilkan daftar lingkungan

Setiap organisasi di Apigee Edge memiliki setidaknya dua lingkungan: test dan prod. Perbedaannya bersifat tidak tentu. Tujuannya adalah memberi Anda area untuk memverifikasi bahwa proxy API Anda berfungsi dengan baik sebelum Anda membukanya untuk developer luar.

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

Lingkungan juga menyediakan pemisahan data dan resource. Misalnya, Anda dapat menyiapkan cache yang berbeda saat 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" ]

Pelajari deployment

Deployment adalah revisi proxy API yang telah di-deploy di lingkungan. Proxy API yang berada 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 sebelum di-deploy. Layanan API mengekspos RESTful API 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 dibatalkan deploymentnya. Anda dapat mengontrol apakah paket baru akan di-deploy sebagai revisi baru atau menimpa 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, lalu tetapkan ke true.

Anda tidak dapat men-deploy satu revisi proxy API di atas revisi yang lain. Fungsi pertama harus selalu dibatalkan deploymentnya. Dengan menetapkan override ke true, Anda menunjukkan bahwa satu revisi proxy API harus di-deploy pada revisi yang saat ini di-deploy. Hasilnya adalah urutan deployment dibatalkan--revisi baru di-deploy, dan setelah deployment selesai, revisi yang sudah di-deploy akan dibatalkan deployment-nya.

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 menetapkan parameter delay. Parameter delay menentukan interval waktu, dalam detik, yang mana revisi sebelumnya harus dibatalkan deployment. Akibatnya, transaksi yang sedang berlangsung memiliki interval waktu yang harus diselesaikan sebelum proxy API yang memproses transaksinya dibatalkan deployment-nya. Berikut adalah hal yang terjadi dengan override=true dan kumpulan parameter delay:

  • Revisi 1 sedang menangani permintaan.
  • Revisi 2 sedang di-deploy secara paralel.
  • Saat 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 sudah 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 dibatalkan deployment.
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
Parameter Kueri Deskripsi
override

Defaultnya adalah false (perilaku deployment normal: revisi yang ada tidak di-deploy, kemudian revisi baru di-deploy).

Tetapkan ke true untuk mengganti perilaku deployment normal dan memberikan deployment yang lancar. Revisi yang ada tetap di-deploy, sedangkan revisi baru juga sedang di-deploy. Jika revisi baru di-deploy, revisi lama tidak akan di-deploy. Gunakan bersama dengan parameter delay untuk mengontrol kapan pembatalan deployment terjadi.
delay

Agar pemrosesan transaksi dapat diselesaikan pada revisi yang ada sebelum revisi tersebut dibatalkan deploymentnya, dan menghilangkan kemungkinan 502 Bad Gateway atau 504 Gateway Timeout errors, tetapkan parameter ini ke jumlah detik penundaan pembatalan deployment yang Anda inginkan. Tidak ada batasan jumlah detik yang dapat ditetapkan, dan tidak ada konsekuensi performa jika menetapkan jumlah detik yang besar. Selama penundaan, tidak ada traffic baru yang dikirim ke revisi lama.

Defaultnya adalah 0 (nol) detik. Jika override ditetapkan ke benar (true) dan delay adalah 0, revisi yang ada akan segera dibatalkan deploymentnya setelah revisi baru di-deploy. Nilai negatif diperlakukan sebagai 0 (nol) detik.

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

Lihat 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. Anda tidak dapat mengubah setelan ini, kecuali jika Anda menggunakan Apigee Edge secara lokal.

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

Lihat 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 menampilkan hasil yang sama seperti di atas untuk setiap API yang di-deploy di lingkungan pengujian

Lihat semua deployment di organisasi Anda

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

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

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

Karena API ini 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 dari proxy API adalah dalam notasi objek JavaScript (JSON). Berikut adalah respons JSON default untuk permintaan POST di atas, yang membuat proxy API bernama weatherapi. Deskripsi setiap elemen pada profil 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 dihasilkan menunjukkan struktur lengkap proxy API:

  • APIProxy revision: Iterasi dengan nomor urut dari konfigurasi proxy API, seperti yang 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 yang mudah digunakan untuk proxy API
  • LastModifiedAt: Waktu saat proxy API dibuat, dengan format 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 yang telah diberi nama
  • Resources: Daftar resource (JavaScript, Python, Java, XSLT) yang tersedia untuk dijalankan di proxy API ini
  • TargetServers: Daftar TargetServers bernama (yang dapat dibuat menggunakan API pengelolaan), yang digunakan dalam konfigurasi lanjutan untuk tujuan load balancing
  • TargetEndpoints: Daftar TargetEndpoints yang 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

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

Menggabungkan 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 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 menyediakan semua setelan Anda untuk skrip shell yang menggabungkan alat deployment.

Sekarang buat skrip shell yang mengimpor setelan tersebut dan menggunakannya untuk memanggil alat deployment. (Sebagai 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 memudahkan 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}"

Langsung memanggil API

Ada baiknya Anda menulis skrip shell sederhana yang mengotomatiskan proses upload dan deployment proxy API.

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

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