Kebijakan ExtensionInfo

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

Gunakan kebijakan ExtensionInfo untuk menyertakan ekstensi ke 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. Tetapi sumber daya dapat berupa sumber daya eksternal apa pun yang dapat diakses melalui HTTP atau HTTPS.

Untuk ringkasan tentang ekstensi, lihat Apa yang dimaksud dengan 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.

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

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

Tentang kebijakan InfoEkstensi

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 bersifat khusus untuk resource. Misalnya, jika kebijakan ini akan mengakses database Cloud Firestore, Anda harus mengetahui nama dokumen dan koleksi yang ingin dibuat atau diakses. Anda biasanya akan menggunakan informasi khusus resource dalam mengonfigurasi penanganan permintaan dan respons kebijakan ini.
• Ekstensi yang ditambahkan, dikonfigurasi, dan di-deploy lingkungan tempat proxy API Anda akan di-deploy. Dengan kata lain, {i>SUMIF<i} memiliki daftar sel jika Anda akan menggunakan kebijakan ini untuk mengakses layanan Google Cloud tertentu, ekstensi yang di-deploy untuk layanan tersebut harus ada di lingkungan Anda. Detail konfigurasi biasanya mencakup informasi yang diperlukan untuk penyempitan akses ke sumber daya, misalnya ID proyek atau nama akun.

Menggunakan kebijakan Extensioncallout dalam 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 {i>logging<i}. Untuk mengetahui detail tentang penggunaan PostClientFlow, lihat Referensi konfigurasi proxy API.

Jika Anda ingin menggunakan kebijakan ExtensionInfo 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 Public Cloud, Tanda features.allowExtensionsInPostClientFlow ditetapkan ke true secara default.

• Jika Anda adalah pelanggan Apigee Edge untuk Private Cloud, gunakan API Memperbarui properti organisasi untuk menyetel tanda features.allowExtensionsInPostClientFlow ke true.

Semua batasan dalam pemanggilan kebijakan MessageLogging dari PostClientFlow juga berlaku untuk kebijakan EkstensiInfo. 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>

&lt;ConnectorCallout&gt; atribut

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

&lt;Action&gt; elemen

Tindakan yang diekspos oleh ekstensi yang harus dipanggil oleh kebijakan.

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

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 ekstensi yang Anda panggil dari kebijakan ini.

<Konektor> elemen

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>

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

&lt;Input&gt; elemen

JSON yang berisi isi permintaan yang akan dikirim ke ekstensi.

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

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

Perlu diketahui bahwa meskipun banyak nilai elemen <Input> yang akan berfungsi dengan benar tanpa dibatasi 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 tersusun dengan baik yang propertinya menentukan nilai untuk dikirim ke tindakan ekstensi yang akan dipanggil. Misalnya, Ekstensi Google Cloud Logging tindakan log ekstensi mengambil nilai yang menentukan log yang menjadi tujuan penulisan (logName), metadata yang 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 digabungkan dengan tanda kurung kurawal akan diganti 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 dalam tanda kutip saat runtime, pastikan untuk menggunakan tanda kutip dalam kode JSON Anda. Hal ini berlaku bahkan saat Anda menentukan variabel alur sebagai nilai properti JSON yang akan diselesaikan saat runtime.

Contoh <Input> berikut menyertakan dua referensi variabel alur:

<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 string example-log.
• Nilai properti metadata -- nilai variabel flow my.log.entry.metadata tanpa menyertakan tanda kutip. Hal ini dapat berguna jika nilai variabel itu sendiri adalah JSON yang mewakili sebuah objek.
• Nilai properti message -- nilai variabel flow client.ip dengan menyertakan tanda kutip.

&lt;Output&gt; elemen

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 respons ditempatkan ke dalam variabel yang Anda tentukan di sini, sehingga Anda dapat mengaksesnya dari kode proxy API lain.

Objek respons ekstensi menggunakan 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 output extensionOutput, Anda dapat mengakses ID pesan tersebut dalam kebijakan lain menggunakan variabel {extensionOutput.messageId}.
• Tidak diurai: Variabel output berisi respons JSON mentah dan tidak diurai dari ekstensi. (Jika ingin, Anda tetap dapat mengurai nilai respons pada langkah terpisah menggunakan kebijakan JavaScript.)

&lt;Output&gt; Atribut

Variabel flow

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.