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

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 API
• APIProxy name: Nama unik proxy API
• ConfigurationVersion: Versi Layanan API tempat proxy API konfigurasi sesuai
• CreatedAt: Waktu saat proxy API dibuat, dengan format dalam waktu UNIX
• CreatedBy: Alamat email pengguna Apigee Edge yang membuat API {i>proxy<i}
• DisplayName: Nama yang mudah digunakan untuk proxy API
• LastModifiedAt: Waktu saat proxy API dibuat, dalam format UNIX waktu
• LastModifiedBy: Alamat email pengguna Apigee Edge yang membuat API {i>proxy<i}
• 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 dalam proxy API ini
• TargetServers: Daftar TargetServers bernama (yang dapat dibuat menggunakan management API), yang digunakan dalam konfigurasi lanjutan untuk tujuan load balancing
• TargetEndpoints: 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