Kebijakan ExtensionInfo

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

Gunakan kebijakan ExtensionCallout untuk menggabungkan ekstensi ke dalam proxy API.

Ekstensi memberikan akses ke resource tertentu di luar Apigee Edge. Resource dapat berupa layanan Google Cloud Platform seperti Cloud Storage atau Cloud Speech-to-Text. Namun, resource dapat berupa resource eksternal apa pun yang dapat diakses melalui HTTP atau HTTPS.

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

Di bawah ini 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 tutorial lengkap menggunakan ekstensi Cloud Logging.

Untuk contoh semua ekstensi yang tersedia, lihat Ringkasan referensi ekstensi.

Tentang kebijakan ExtensionCallout

Gunakan kebijakan ExtensionCallout saat Anda ingin menggunakan ekstensi yang dikonfigurasi untuk mengakses resource eksternal dari dalam proxy API.

Sebelum menggunakan kebijakan ini, Anda memerlukan:

• Beberapa detail tentang resource eksternal yang ingin Anda akses dari kebijakan ini. Detail ini akan khusus untuk resource. Misalnya, jika kebijakan akan mengakses database Cloud Firestore Anda, Anda harus mengetahui nama koleksi dan dokumen yang ingin Anda buat atau akses. Anda biasanya akan menggunakan informasi khusus resource dalam mengonfigurasi penanganan permintaan dan respons kebijakan ini.
• Ekstensi 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 mencakup informasi yang diperlukan untuk mempersempit akses ke resource, seperti ID project 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 pencatatan. Untuk mengetahui detail tentang penggunaan PostClientFlow, lihat Referensi konfigurasi proxy API.

Jika Anda ingin menggunakan kebijakan ExtensionCallout untuk memanggil ekstensi Google Cloud Logging dari PostClientFlow, pastikan tanda features.allowExtensionsInPostClientFlow disetel ke true di organisasi Anda.

• Jika Anda adalah pelanggan Apigee Edge for Public Cloud, flag features.allowExtensionsInPostClientFlow disetel ke true secara default.

• Jika Anda adalah pelanggan Apigee Edge untuk Private Cloud, gunakan API Update organization properties untuk menyetel flag features.allowExtensionsInPostClientFlow ke true.

Semua batasan pada pemanggilan kebijakan MessageLogging dari PostClientFlow juga berlaku untuk kebijakan ExtensionCallout. Lihat Catatan penggunaan untuk mengetahui 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 umum untuk semua elemen induk kebijakan:

&lt;DisplayName&gt; elemen

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI dengan nama natural language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Elemen <Action>

Tindakan yang diekspos ekstensi yang harus dipanggil oleh kebijakan.

<Action>action-exposed-by-extension</Action>

Setiap ekstensi mengekspos serangkaian tindakannya sendiri yang memberikan akses ke fungsi resource yang diwakili ekstensi. 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 mengetahui 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 ke ekstensi saat dikonfigurasi untuk di-deploy ke lingkungan.

<Connector>name-of-configured-extension</Connector>

Ekstensi memiliki nilai konfigurasi yang mungkin berbeda dari ekstensi lain yang di-deploy berdasarkan paket ekstensi yang sama. Nilai konfigurasi ini dapat menunjukkan perbedaan penting dalam fungsi runtime antara ekstensi yang dikonfigurasi dari paket yang sama, jadi pastikan untuk menentukan ekstensi yang benar untuk dipanggil.

Elemen <Input>

JSON yang berisi isi permintaan untuk dikirim ke ekstensi.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Ini pada dasarnya 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 properti setiap tindakan.

Perhatikan bahwa meskipun banyak nilai elemen <Input> akan berfungsi dengan benar tanpa disertakan sebagai bagian <![CDATA[]]>, aturan JSON memungkinkan nilai yang tidak akan diuraikan sebagai XML. Sebagai praktik terbaik, sertakan JSON sebagai bagian CDATA untuk menghindari error penguraian saat runtime.

Nilai elemen <Input> adalah JSON yang disusun dengan baik yang propertinya menentukan nilai yang akan dikirim ke tindakan ekstensi untuk dipanggil. Misalnya, tindakan log 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 alur di JSON <Input>

Konten <Input> diperlakukan sebagai template pesan. Artinya, nama variabel yang diapit tanda kurung kurawal akan diganti saat runtime dengan nilai variabel yang dirujuk.

Misalnya, Anda dapat menulis ulang blok <Input> sebelumnya untuk menggunakan flow variable 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 dalam JSON diapit tanda kutip saat runtime, pastikan untuk menggunakan tanda kutip dalam kode JSON Anda. Hal ini berlaku meskipun Anda menentukan variabel alur sebagai nilai properti JSON yang akan diselesaikan saat runtime.

Contoh <Input> berikut menyertakan dua referensi flow variable:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

Saat runtime, nilai properti JSON akan diselesaikan sebagai berikut:

• Nilai properti logName -- literal string example-log.
• Nilai properti metadata -- nilai variabel alur my.log.entry.metadata tanpa tanda petik penutup. Hal ini dapat berguna jika nilai variabel itu sendiri adalah JSON yang merepresentasikan objek.
• Nilai properti message -- nilai variabel alur client.ip dengan tanda kutip di dalamnya.

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

Saat respons diterima, nilai tanggapan ditempatkan ke dalam variabel yang Anda tentukan di sini, tempat Anda dapat mengaksesnya dari kode Proxy API lainnya.

Objek respons ekstensi dalam format JSON. Ada dua opsi untuk cara kebijakan menangani JSON:

• Diurai (default): Kebijakan mengurai objek JSON dan otomatis membuat variabel dengan data JSON. Misalnya, jika JSON berisi "messageId" : 12345; dan Anda memberi nama variabel output extensionOutput, Anda dapat mengakses ID pesan tersebut di kebijakan lain menggunakan variabel {extensionOutput.messageId}.
• Tidak diuraikan: Variabel output berisi respons JSON mentah yang tidak diuraikan dari ekstensi. (Jika mau, Anda tetap dapat mengurai nilai respons dalam langkah terpisah menggunakan kebijakan JavaScript.)

Atribut <Output>

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.

Error deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.