Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Gunakan kebijakan ExtensionCallout untuk memasukkan ekstensi ke proxy API.
Ekstensi menyediakan akses ke resource tertentu yang eksternal ke Apigee Edge. Resource ini dapat berupa layanan Google Cloud Platform seperti Cloud Storage atau Cloud Speech-to-Text. Tetapi resource dapat berupa resource eksternal apa pun yang dapat diakses melalui HTTP atau HTTPS.
Untuk ringkasan tentang ekstensi, lihat Apa itu ekstensi? Untuk tutorial pengantar, lihat Tutorial: Menambahkan dan menggunakan ekstensi.
Sebelum mengakses ekstensi dari kebijakan ExtensionCallout, Anda harus menambahkan, mengonfigurasi, dan men-deploy ekstensi dari paket ekstensi yang sudah diinstal ke organisasi Apigee Edge Anda.
Contoh
Berikut adalah contoh kebijakan untuk digunakan dengan ekstensi Cloud Logging:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
<DisplayName>Logging Extension</DisplayName>
<Connector>cloud-extension-sample</Connector>
<Action>log</Action>
<Input>{
"logName" : "example-log",
"metadata" : "test-metadata",
"message" : "This is a test"
}</Input>
<Output>cloud-extension-example-log</Output>
</ConnectorCallout>
Lihat Tutorial: Menggunakan ekstensi untuk mengetahui tutorial lengkap menggunakan ekstensi Cloud Logging.
Untuk mengetahui contoh semua ekstensi yang tersedia, lihat Ringkasan referensi ekstensi.
Tentang kebijakan ExtensionInfo
Gunakan kebijakan ExtensionCallout jika Anda ingin menggunakan ekstensi yang dikonfigurasi untuk mengakses resource eksternal dari dalam proxy API.
Sebelum menggunakan kebijakan ini, Anda perlu:
- Beberapa detail tentang resource eksternal yang ingin Anda akses dari kebijakan ini. Detail ini akan berlaku khusus untuk resource. Misalnya, jika kebijakan akan mengakses database Cloud Firestore, Anda harus mengetahui nama koleksi dan dokumen yang ingin dibuat atau diakses. Anda biasanya akan menggunakan informasi spesifik per resource dalam mengonfigurasi penanganan permintaan dan respons kebijakan ini.
- Ekstensi yang ditambahkan, dikonfigurasi, dan di-deploy ke lingkungan tempat proxy API Anda akan di-deploy. Dengan kata lain, jika Anda akan menggunakan kebijakan ini untuk mengakses layanan Google Cloud tertentu, maka ekstensi yang di-deploy untuk layanan tersebut harus ada di lingkungan Anda. Detail konfigurasi biasanya menyertakan informasi yang diperlukan untuk mempersempit akses ke resource, seperti project ID atau nama akun.
Menggunakan kebijakan ExtensionCallout di PostClientFlow
Anda dapat memanggil kebijakan ExtensionCallout dari PostClientFlow proxy API. PostClientFlow dijalankan setelah respons dikirim ke klien yang meminta, yang memastikan bahwa semua metrik tersedia untuk logging. Untuk detail tentang penggunaan PostClientFlow, lihat Referensi konfigurasi proxy API.
Jika Anda ingin menggunakan kebijakan ExtensionCallout untuk memanggil ekstensi Google Cloud Logging dari PostClientFlow, pastikan flag features.allowExtensionsInPostClientFlow
ditetapkan ke true
di organisasi Anda.
Jika Anda adalah pelanggan Apigee Edge untuk Cloud Publik, tanda
features.allowExtensionsInPostClientFlow
disetel ketrue
secara default.Jika Anda adalah pelanggan Apigee Edge untuk Private Cloud, gunakan Update organization properties API untuk menetapkan tanda
features.allowExtensionsInPostClientFlow
ketrue
.
Semua batasan untuk memanggil kebijakan MessageLogging dari PostClientFlow juga berlaku untuk kebijakan ExtensionCallout. Lihat Catatan penggunaan untuk informasi selengkapnya.
Referensi elemen
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
<DisplayName/>
<Connector/>
<Action/>
<Input/>
<Output/>
</ConnectorCallout>
Atribut <ConnectorCallout>
<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">
Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Wajib |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini sudah tidak digunakan lagi. |
false | Tidak digunakan lagi |
Elemen <DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Ketersediaan | Opsional |
Jenis | String |
Elemen <Action>
Tindakan yang mengekspos ekstensi yang harus dipanggil oleh kebijakan.
<Action>action-exposed-by-extension</Action>
Default | Tidak ada |
---|---|
Ketersediaan | Wajib |
Jenis | String |
Setiap ekstensi mengekspos kumpulan tindakannya sendiri yang memberikan akses ke fungsi resource yang diwakili ekstensi tersebut. Anda dapat menganggap tindakan sebagai fungsi yang Anda panggil dengan kebijakan ini, menggunakan konten elemen <Input>
untuk menentukan argumen fungsi. Respons tindakan disimpan dalam variabel yang Anda tentukan dengan elemen <Output>
.
Untuk daftar fungsi ekstensi, lihat referensi untuk ekstensi yang Anda panggil dari kebijakan ini.
Elemen <Connector>
Nama ekstensi yang dikonfigurasi untuk digunakan. Ini adalah nama cakupan lingkungan yang diberikan ekstensi saat dikonfigurasi untuk deployment ke lingkungan.
<Connector>name-of-configured-extension</Connector>
Default | Tidak ada |
---|---|
Ketersediaan | Wajib |
Jenis | String |
Ekstensi memiliki nilai konfigurasi yang mungkin berbeda dari ekstensi lain yang di-deploy berdasarkan paket ekstensi yang sama. Nilai konfigurasi ini dapat merepresentasikan perbedaan penting dalam fungsi runtime antar-ekstensi yang dikonfigurasi dari paket yang sama, jadi pastikan untuk menentukan ekstensi yang benar untuk dipanggil.
Elemen <Input>
JSON yang berisi isi permintaan yang akan dikirim ke ekstensi.
<Input><![CDATA[ JSON-containing-input-values ]]></Input>
Default | Tidak ada |
---|---|
Ketersediaan | Opsional atau wajib, bergantung pada ekstensinya. |
Jenis | String |
Pada dasarnya, ini adalah argumen untuk tindakan yang Anda tentukan dengan elemen <Action>
. Nilai elemen <Input>
akan bervariasi, bergantung pada ekstensi dan tindakan yang Anda panggil. Lihat dokumentasi paket ekstensi untuk mengetahui detail tentang setiap properti tindakan.
Perhatikan bahwa meskipun banyak nilai elemen <Input>
akan berfungsi dengan benar tanpa dikurung sebagai bagian <![CDATA[]]>
, aturan JSON mengizinkan nilai yang tidak akan diurai sebagai XML. Sebagai praktik terbaik, sertakan JSON sebagai bagian CDATA
untuk menghindari error penguraian runtime.
Nilai elemen <Input>
adalah JSON yang diformat dengan baik dan propertinya menentukan nilai yang akan dikirim ke tindakan ekstensi yang akan dipanggil. Misalnya, tindakan log
pada ekstensi Google Cloud Logging Extension mengambil nilai yang menentukan log yang akan ditulis (logName
), metadata yang akan disertakan dengan entri (metadata
), dan pesan log (data
). Berikut contohnya:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {
"resource": {
"type": "global",
"labels": {
"project_id": "my-test"
}
}
},
"message" : "This is a test"
}]]></Input>
Menggunakan variabel flow di JSON <Input>
Konten <Input>
diperlakukan sebagai
template pesan. Artinya, nama variabel yang dimasukkan dalam tanda kurung kurawal akan diganti pada saat runtime dengan nilai variabel yang direferensikan.
Misalnya, Anda dapat menulis ulang blok <Input>
sebelumnya untuk menggunakan variabel alur client.ip
guna mendapatkan alamat IP klien yang memanggil proxy API:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {
"resource": {
"type": "global",
"labels": {
"project_id": "my-test"
}
}
},
"message" : "{client.ip}"
}]]></Input>
Jika Anda ingin nilai properti di JSON diapit dengan tanda kutip saat runtime, pastikan untuk menggunakan tanda kutip dalam kode JSON Anda. Hal ini berlaku meskipun Anda menentukan variabel flow sebagai nilai properti JSON yang akan di-resolve saat runtime.
Contoh <Input>
berikut menyertakan dua referensi variabel flow:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {my.log.entry.metadata},
"message" : "{client.ip}"
}]]></Input>
Saat runtime, nilai properti JSON akan di-resolve sebagai berikut:
- Nilai properti
logName
-- literal stringexample-log
. - Nilai properti
metadata
-- nilai variabel alurmy.log.entry.metadata
tanpa tanda petik. Hal ini dapat berguna jika nilai variabel itu sendiri JSON yang mewakili sebuah objek. - Nilai properti
message
-- nilai variabel alurclient.ip
dengan tanda petik.
Elemen <Output>
Nama variabel yang menyimpan respons tindakan ekstensi.
<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->
atau
<Output parsed="false">variable-name</Output> <!-- The JSON object inside the variable is raw, unparsed -->
Default | Tidak ada |
---|---|
Ketersediaan | Opsional atau wajib, bergantung pada ekstensinya. |
Jenis | String atau objek yang diurai, bergantung pada setelan atribut parsed . |
Saat respons diterima, nilai respons ditempatkan ke dalam variabel yang Anda tentukan di sini, dan dapat diakses dari kode proxy API lainnya.
Objek respons ekstensi memiliki format JSON. Ada dua opsi terkait cara kebijakan menangani JSON:
- Diurai (default): Kebijakan ini mengurai objek JSON dan otomatis menghasilkan variabel dengan data JSON. Misalnya, jika JSON berisi
"messageId" : 12345;
dan Anda memberi nama variabel outputextensionOutput
, Anda dapat mengakses ID pesan tersebut dalam kebijakan lain menggunakan variabel{extensionOutput.messageId}
. - Tidak diurai: Variabel output berisi respons JSON mentah yang tidak diurai dari ekstensi. (Jika mau, Anda masih dapat mengurai nilai respons dalam langkah terpisah menggunakan kebijakan JavaScript.)
Atribut <Output>
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
diuraikan | Mengurai objek JSON yang ditampilkan dari ekstensi, yang memungkinkan data dalam objek JSON diakses sebagai variabel oleh kebijakan lain. | true | Opsional |
Variabel alur
Tidak ada.
Kode error
Error yang ditampilkan dari kebijakan Apigee Edge mengikuti format yang konsisten seperti yang dijelaskan dalam Referensi error kebijakan.
Bagian ini menjelaskan pesan error dan variabel flow yang ditetapkan saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk proxy. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Penanganan kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dijalankan.
Nama error | Status HTTP | Penyebab |
---|---|---|
Eksekusi Gagal | 500 |
Ekstensi merespons dengan error. |
Error deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Terjadi saat | Perbaiki |
---|---|---|
InvalidConnectorInstance |
Elemen <Connector> kosong. |
build |
ConnectorInstanceDoesNotExists |
Ekstensi yang ditentukan dalam elemen <Connector> tidak ada di lingkungan. |
build |
InvalidAction |
Elemen <Action> dalam kebijakan ExtensionInfo
tidak ada atau ditetapkan ke nilai kosong. |
build |
AllowExtensionsInPostClientFlow |
Dilarang memiliki kebijakan ExtensionInfo dalam Flow PostClient. | build |