Halaman ini diterjemahkan oleh Cloud Translation API.

Kebijakan ExtensionInfo

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 ke true secara default.
Jika Anda adalah pelanggan Apigee Edge untuk Private Cloud, gunakan Update organization properties API untuk menetapkan tanda features.allowExtensionsInPostClientFlow ke true.

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 `name` dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Atau, gunakan elemen `<DisplayName>` untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.	T/A	Wajib
`continueOnError`	Setel ke `false` untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke `true` agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal.	false	Opsional
`enabled`	Setel ke `true` untuk menerapkan kebijakan. Setel ke `false` untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.	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

Default	T/A Jika Anda menghapus elemen ini, nilai atribut `name` kebijakan akan digunakan.
Ketersediaan	Opsional
Jenis	String

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.

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 string example-log.
Nilai properti metadata -- nilai variabel alur my.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 alur client.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 output extensionOutput, 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.
`ConnectorInstanceDoesNotExists`	Ekstensi yang ditentukan dalam elemen `<Connector>` tidak ada di lingkungan.
`InvalidAction`	Elemen `<Action>` dalam kebijakan ExtensionInfo tidak ada atau ditetapkan ke nilai kosong.
`AllowExtensionsInPostClientFlow`	Dilarang memiliki kebijakan ExtensionInfo dalam Flow PostClient.