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 didemonstrasikan dalam topik ini dapat digunakan untuk mengintegrasikan 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 dalam hal ini orang lain). Sebaliknya, alat ini mengekspos fungsi atomik yang dapat dikoordinasikan oleh tim pengembangan Anda 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 dapat melakukannya dengan salah satu metode berikut:
- OAuth2 (khusus Cloud Publik)
- SAML (Cloud Publik dan Pribadi)
- Autentikasi Dasar (tidak direkomendasikan; Cloud Publik dan Pribadi)
Topik ini berfokus pada kumpulan 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. (Jangan lupa untuk mengganti entri untuk EMAIL:PASSWORD dan ORG_NAME. Untuk mengetahui petunjuknya, 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
di proxy API apa pun di organisasi Anda. Panggilan ini akan mengembalikan 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 dikembalikan oleh metode ini adalah nama proxy API bersama revision, yang memiliki nomor terkait. Proxy API terdiri dari paket konfigurasi . Revisi memberikan mekanisme ringan untuk mengelola pembaruan konfigurasi saat Anda mengulanginya. Revisi diberi nomor urut, yang memungkinkan Anda mengembalikan perubahan dengan men-deploy revisi sebelumnya dari proxy API Anda. Selain itu, Anda dapat men-deploy revisi proxy API ke dalam prod, sambil terus membuat revisi baru dari proxy API tersebut dalam pengujian lingkungan fleksibel App Engine. Jika sudah siap, Anda dapat mempromosikan revisi proxy API yang lebih tinggi dari lingkungan pengujian terhadap revisi proxy API sebelumnya di lingkungan produksi.
Dalam contoh ini, hanya ada satu revisi karena proxy API baru saja dibuat. Sebagai API proxy bergerak melalui siklus proses dari konfigurasi dan deployment berulang, angka revisi pertambahan inkremental dengan bilangan bulat. Dengan menggunakan panggilan API langsung untuk men-deploy, Anda dapat secara opsional meningkatkan nomor revisi proxy API. Terkadang ketika Anda membuat perubahan kecil, Anda mungkin tidak ingin menambah revisi.
Mendapatkan Revisi API
Versi API (misalnya, api.company.com/v1
) seharusnya sangat berubah
jarang. Ketika Anda menambah versi API, itu menandakan
kepada pengembang bahwa ada
terjadi perubahan signifikan dalam tanda tangan antarmuka eksternal yang diekspos oleh API.
Revisi proxy API adalah angka bertambah yang terkait dengan proxy API
konfigurasi Anda. Layanan API mempertahankan revisi konfigurasi sehingga Anda dapat mengembalikan
konfigurasi saat terjadi kesalahan. Secara default, revisi proxy API akan otomatis
bertambah setiap kali Anda mengimpor proxy API menggunakan API Import an API proxy. Jika Anda
tidak ingin menambah revisi proxy API, gunakan opsi
API revisi proxy. Jika Anda menggunakan Maven untuk men-deploy, gunakan clean
atau
update
opsi, seperti yang dijelaskan dalam plugin Maven
readme.
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 pada proxy API di test
, lalu jika sudah 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
di lingkungan production.
Proxy API tidak dapat dipanggil sebelum di-deploy ke lingkungan. Setelah Anda memiliki
men-deploy revisi proxy API ke produksi, Anda kemudian dapat memublikasikan URL prod
ke
developer.
Cara membuat daftar lingkungan
Setiap organisasi di Apigee Edge memiliki setidaknya dua lingkungan: test
dan prod
. Tujuan
perbedaannya bersifat arbitrer. Tujuannya adalah untuk memberi Anda area untuk memverifikasi bahwa proxy API Anda
bekerja dengan baik sebelum Anda
membukanya untuk pengembang luar.
Setiap lingkungan benar-benar merupakan alamat jaringan, memungkinkan Anda untuk memisahkan lalu lintas antara Proxy API yang sedang Anda kerjakan, dan yang sedang diakses oleh aplikasi saat runtime.
Lingkungan juga menyediakan pemisahan data dan resource. Misalnya, Anda dapat menyiapkan cache berbeda dalam pengujian dan produksi, yang hanya dapat diakses oleh proxy API yang mengeksekusi lingkungan fleksibel App Engine.
Melihat lingkungan di organisasi
curl -u EMAIL:PASSWORD \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments
Contoh Respons
[ "test", "prod" ]
Mempelajari deployment
Deployment adalah revisi proxy API yang telah di-deploy di lingkungan. Sebuah API
proxy yang berada dalam status di-deploy dapat diakses melalui jaringan, di alamat yang ditentukan di
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 perlu dibatalkan deployment-nya. Anda dapat mengontrol apakah paket baru di-deploy atau tidak sebagai revisi baru atau apakah akan 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:
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 yang 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 ke revisi yang lain. Yang pertama harus selalu
tidak di-deploy. Dengan menyetel override
ke true
, Anda menunjukkan bahwa ada satu revisi
proxy API harus di-deploy pada revisi yang saat ini di-deploy. Hasilnya adalah bahwa
urutan deployment dibalik--revisi baru di-deploy, dan setelah deployment
selesai, revisi yang telah di-deploy tidak di-deploy.
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
. Tujuan
Parameter delay
menentukan interval waktu, dalam detik, sebelum interval waktu
revisi harus dibatalkan deployment. Akibatnya, transaksi yang sedang berlangsung
memiliki interval waktu pada
yang harus diselesaikan sebelum proxy API yang memproses transaksinya tidak di-deploy. Mengikuti adalah
apa yang terjadi dengan override=true
dan parameter delay
yang ditetapkan:
- Revisi 1 menangani permintaan.
- Revisi 2 di-deploy secara paralel.
- Saat Revisi 2 di-deploy sepenuhnya, traffic baru dikirim ke Revisi 2. Tidak ada traffic baru dikirim ke Revisi 1.
- Namun, Revisi 1 mungkin masih memproses transaksi yang ada. Dengan menetapkan
delay
(misalnya, 15 detik), Anda memberikan waktu 15 detik untuk Revisi 1 menyelesaikan transaksi yang ada. - Setelah interval penundaan, Revisi 1 tidak di-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
Parameter Kueri | Deskripsi |
---|---|
override |
Defaultnya adalah Setel ke |
delay |
Untuk memungkinkan pemrosesan transaksi selesai pada revisi yang ada sebelum revisi
tidak di-deploy—dan menghilangkan kemungkinan Defaultnya adalah 0 (nol) detik. Jika |
Jika override=true
digunakan bersama dengan delay
, HTTP 5XX
yang dihasilkan selama deployment dapat dihilangkan. Ini karena kedua revisi
proxy API akan
di-deploy secara bersamaan, dengan revisi lama tidak di-deploy setelah penundaan.
Lihat semua deployment API Revisi
Terkadang Anda perlu mengambil daftar semua revisi API yang saat ini di-deploy {i>proxy<i}.
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 lokal.
Properti penting yang terdapat dalam respons adalah organization
,
environment
, aPIProxy
, name
, dan state
. Menurut
meninjau nilai properti ini, Anda dapat memastikan
bahwa revisi tertentu dari proxy API telah
yang di-deploy di suatu lingkungan.
Lihat semua deployment dalam lingkungan pengujian
Anda juga bisa mengambil status deployment untuk lingkungan tertentu (termasuk revisi nomor 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
Lihat semua deployment di organisasi
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-nya adalah RESTful, Anda cukup menggunakan metode POST
, beserta JSON atau XML
terhadap resource yang sama untuk membuat proxy API.
Profil untuk proxy API Anda telah dibuat. Representasi default dari proxy API berada dalam
Notasi objek JavaScript (JSON). Di bawah ini adalah respons JSON default untuk permintaan POST
di atas,
yang membuat proxy API bernama weatherapi
. Deskripsi setiap elemen di profil
berikut ini:
{ "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 API {i>proxy<i}:
APIProxy revision
: Iterasi proxy API yang diberi nomor urut konfigurasinya, seperti yang dikelola oleh Layanan APIAPIProxy name
: Nama unik proxy APIConfigurationVersion
: Versi Layanan API tempat proxy API konfigurasi sesuaiCreatedAt
: Waktu saat proxy API dibuat, dengan format dalam waktu UNIXCreatedBy
: Alamat email pengguna Apigee Edge yang membuat API {i>proxy<i}DisplayName
: Nama yang mudah digunakan untuk proxy APILastModifiedAt
: Waktu saat proxy API dibuat, dalam format UNIX waktuLastModifiedBy
: Alamat email pengguna Apigee Edge yang membuat API {i>proxy<i}Policies
: Daftar kebijakan yang telah ditambahkan ke proxy API iniProxyEndpoints
: Daftar ProxyEndpoint bernamaResources
: Daftar resource (JavaScript, Python, Java, XSLT) yang tersedia untuk dieksekusi dalam proxy API iniTargetServers
: Daftar TargetServers bernama (yang dapat dibuat menggunakan management API), yang digunakan dalam konfigurasi lanjutan untuk tujuan load balancingTargetEndpoints
: Daftar TargetEndpoint bernama
Perlu diketahui bahwa banyak elemen konfigurasi proxy API yang dibuat menggunakan POST
sederhana
metode di atas kosong. Dalam topik berikut, Anda akan mempelajari cara menambahkan dan mengonfigurasi kunci
komponen proxy API.
Anda juga dapat membaca tentang elemen konfigurasi ini di referensi konfigurasi proxy API.
Pembuatan skrip terhadap API
Halaman Menggunakan proxy API contoh, yang tersedia di GitHub menyediakan skrip shell yang menggabungkan alat deploy Apigee. Jika karena alasan tertentu Anda tidak dapat menggunakan alat deploy Python, maka Anda dapat memanggil API secara langsung. Kedua pendekatan tersebut adalah yang ditunjukkan dalam contoh skrip di bawah ini.
Menggabungkan alat deploy
Pertama, pastikan alat deployment Python yang tersedia di lingkungan lokal Anda.
Kemudian, buat file untuk menyimpan kredensial Anda. Skrip deployment yang Anda tulis akan diimpor
setelan ini, membantu Anda mengelola
kredensial untuk akun Anda secara terpusat. Di API
Contoh platform, 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 menggabungkan deploy menyediakan alat command line gcloud.
Sekarang, buat skrip shell yang mengimpor setelan tersebut dan menggunakannya untuk memanggil alat deployment. (Untuk melihat contohnya, lihat Contoh platform Apigee API.)
#!/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 ini:
#!/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 {i>shell <i}sederhana yang mengotomatiskan proses upload dan men-deploy proxy API.
Skrip di bawah ini langsung memanggil API pengelolaan. Perintah ini membatalkan deployment revisi yang sudah ada
proxy API yang Anda update akan membuat file ZIP dari direktori /apiproxy
yang berisi file konfigurasi proxy Anda, lalu mengunggah, mengimpor, dan menerapkan
konfigurasi Anda.
#!/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