Kebijakan IntegrationCallout

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Ringkasan

Kebijakan IntegrationCallout memungkinkan Anda menjalankan Integrasi Aplikasi yang memiliki pemicu API. Namun, sebelum menjalankan integrasi, Anda harus menjalankan kebijakan SetIntegrationRequest. Kebijakan SetIntegrationRequest membuat objek permintaan dan membuat objek tersedia untuk kebijakan IntegrationCallout sebagai variabel alur. Objek permintaan memiliki detail integrasi seperti nama pemicu API, ID project integrasi, nama integrasi, dan detail lainnya yang dikonfigurasi dalam kebijakan SetIntegrationRequest. Kebijakan IntegrationCallout menggunakan variabel alur objek permintaan untuk menjalankan integrasi. Anda dapat mengonfigurasi kebijakan IntegrationCallout untuk menyimpan respons eksekusi integrasi dalam variabel alur.

Kebijakan IntegrationCallout berguna jika Anda ingin menjalankan integrasi di tengah alur proxy. Atau, alih-alih mengonfigurasi kebijakan IntegrationCallout, Anda juga dapat menjalankan integrasi dengan menentukan endpoint integrasi sebagai target endpoint. Untuk mengetahui informasi selengkapnya, lihat IntegrationEndpoint.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Catatan: Anda memerlukan token autentikasi untuk menjalankan kebijakan IntegrationCallout. Namun, tidak ada elemen Authentication eksplisit dalam definisi kebijakan. Apigee menambahkan token autentikasi ke permintaan di balik layar. Agar kebijakan IntegrationCallout berhasil melakukan autentikasi, Anda harus men-deploy proxy API dengan akun layanan yang memiliki peran IAM yang diperlukan untuk menjalankan integrasi. Untuk mengetahui informasi tentang peran yang diperlukan, lihat Peran IAM untuk integrasi. Untuk mengetahui detail selengkapnya tentang men-deploy proxy API, lihat Men-deploy di Apigee.

<IntegrationCallout>

Menentukan kebijakan IntegrationCallout.

Nilai Default	T/A
Wajib?	Wajib
Jenis	Jenis kompleks
Elemen Induk	T/A
Elemen Turunan	<DisplayName> <AsyncExecution> <Request> <Response>

Tabel berikut memberikan deskripsi umum tentang elemen turunan <IntegrationCallout>:

Elemen Turunan	Wajib?	Deskripsi
<DisplayName>	Opsional	Nama kustom untuk kebijakan.
<AsyncExecution>	Opsional	Menentukan apakah integrasi harus berjalan dalam mode sinkron atau mode asinkron.
<Request>	Wajib	Variabel alur yang memiliki objek permintaan yang dibuat oleh kebijakan SetIntegrationRequest.
<Response>	Opsional	Variabel alur untuk menyimpan respons integrasi.

Elemen <IntegrationCallout> menggunakan sintaksis berikut:

Sintaks

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="[true|false]" enabled="[true|false]" name=POLICY_NAME>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution>
  <Request clearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request>
  <Response>RESPONSE_FLOW_VARIABLE_NAME</Response>
</IntegrationCallout>

Contoh

Contoh berikut menunjukkan definisi kebijakan IntegrationCallout:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="false" enabled="true" name="Integration-Callout">
  <DisplayName>Integration-Callout-1</DisplayName>
  <AsyncExecution>true</AsyncExecution>
  <Request clearPayload="true">my_request_flow_var</Request>
  <Response>my_response_flow_var</Response>
</IntegrationCallout>

Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:

Atribut	Default	Wajib?	Deskripsi
name	T/A	Wajib	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.
continueOnError	false	Opsional	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini
enabled	benar	Opsional	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async	false	Tidak digunakan lagi	Atribut ini tidak digunakan lagi.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <IntegrationCallout>.

<DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default	T/A
Wajib?	Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis	String
Elemen Induk	<PolicyElement>
Elemen Turunan	Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaks

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<AsyncExecution>

Menentukan mode untuk menjalankan integrasi. Anda dapat menjalankan integrasi secara sinkron atau asinkron.

Jika disetel ke true, integrasi akan berjalan secara asinkron. Jika disetel ke false, integrasi akan berjalan secara sinkron.

• Mode asinkron: Saat permintaan untuk menjalankan integrasi mencapai endpoint, endpoint akan segera menampilkan ID eksekusi integrasi, tetapi memulai eksekusi integrasi pada waktu yang ditentukan oleh elemen <ScheduleTime>. Jika Anda belum menyetel elemen <ScheduleTime>, integrasi dijadwalkan untuk segera berjalan. Meskipun integrasi dijadwalkan untuk segera dijalankan, eksekusinya dapat dimulai setelah beberapa detik. Saat integrasi mulai dieksekusi, dua hal berikut akan terjadi:
  • Integrasi menampilkan kode status HTTP 200 OK sehingga pemanggil dapat melanjutkan pemrosesan.
  • Kebijakan IntegrationCallout selesai.
  Setelah dimulai, integrasi akan memiliki batas waktu maksimum 50 menit untuk menyelesaikan eksekusi.
• Mode sinkron: Saat permintaan untuk menjalankan integrasi mencapai endpoint, endpoint akan segera memulai eksekusi integrasi dan menunggu respons. Batas waktu maksimum untuk menyelesaikan eksekusi adalah 2 menit. Setelah menyelesaikan eksekusi, endpoint akan menampilkan respons dengan ID eksekusi dan data respons lainnya.

Nilai Default	false
Wajib?	Opsional
Jenis	Boolean
Elemen Induk	<IntegrationCallout>
Elemen Turunan	Tidak ada

Elemen <AsyncExecution> menggunakan sintaksis berikut:

Sintaks

<AsyncExecution>BOOLEAN</AsyncExecution>

Contoh

Contoh berikut menetapkan eksekusi asinkron ke true:

<AsyncExecution>true</AsyncExecution>

<Request>

Menentukan variabel alur yang memiliki objek permintaan yang dibuat oleh kebijakan SetIntegrationRequest. Kebijakan IntegrationCallout mengirim objek permintaan ini ke Application Integration untuk menjalankan integrasi.

Nilai Default	T/A
Wajib?	Wajib
Jenis	String
Elemen Induk	<IntegrationCallout>
Elemen Turunan	Tidak ada

Elemen <Request> menggunakan sintaksis berikut:

Sintaks

<Request clearPayload="true">FLOW_VARIABLE_NAME</Request>

Contoh

Contoh berikut menentukan bahwa objek permintaan tersedia dalam variabel alur my_request_flow_var:

<Request clearPayload="true">my_request_flow_var</Request>

Tabel berikut menjelaskan atribut <Request>:

Atribut	Wajib?	Jenis	Deskripsi
clearPayload	Opsional	boolean	Menentukan apakah objek permintaan harus dihapus dari memori setelah mengirim permintaan untuk menjalankan integrasi. Jika disetel ke true, Apigee akan menghapus objek permintaan. Jika disetel ke false, Apigee tidak akan menghapus objek permintaan. Jika Anda tidak menentukan atribut ini, nilai defaultnya adalah true dan objek permintaan akan dihapus dari memori.

<Response>

Menentukan variabel alur untuk menyimpan respons integrasi.

Jika Anda tidak menentukan elemen ini, kebijakan akan menyimpan respons dalam variabel alur integration.response.

Nilai Default	integration.response
Wajib?	Opsional
Jenis	String
Elemen Induk	<IntegrationCallout>
Elemen Turunan	Tidak ada

Output integrasi dapat diakses oleh integration.response.content atau flow_variable.content. Elemen <Response> menggunakan sintaksis berikut:

Sintaks

<Response>FLOW_VARIABLE_NAME</Response>

Contoh

Contoh berikut menyimpan respons eksekusi integrasi dalam variabel alur my_response_flow_var:

<Response>my_response_flow_var</Response>

Kode error

Bagian ini menjelaskan kode error, pesan error, dan variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode kerusakan	Status HTTP	Penyebab
entities.UnresolvedVariable	500	Error ini terjadi jika Apigee tidak dapat me-resolve variabel integration.project.id atau integration.name.
steps.integrationcallout.ExecutionFailed	500	Error ini dapat terjadi jika layanan target backend menampilkan status error HTTP seperti 4xx atau 5xx. Kemungkinan penyebabnya meliputi: Akun layanan yang di-deploy dengan proxy memiliki izin yang salah untuk menjalankan integrasi. Integrasi atau pemicu API tidak ada. Integrasi Aplikasi tidak diaktifkan untuk project Google Cloud Anda. Anda telah mengonfigurasi elemen <ScheduleTime> dalam kebijakan SetIntegrationRequest dan kebijakan IntegrationCallout memiliki AsyncExecution yang ditetapkan ke false.
steps.integrationcallout.NullRequestVariable	500	Error ini terjadi jika variabel alur yang ditentukan di <Request> bernilai null.
steps.integrationcallout.RequestVariableNotMessageType	500	Error ini terjadi jika variabel alur yang ditentukan oleh elemen Request bukan dari jenis message.
steps.integrationcallout.RequestVariableNotRequestMessageType	500	Error ini terjadi jika variabel alur yang ditentukan oleh elemen Request bukan dari jenis Pesan permintaan.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure	500	Error ini dapat terjadi karena konfigurasi akun layanan yang salah. Kemungkinan penyebabnya meliputi: Akun layanan yang di-deploy dengan proxy tidak ada dalam project Anda. Akun layanan yang di-deploy dengan proxy dinonaktifkan.

Variabel error

Setiap kali ada error eksekusi dalam kebijakan, Apigee akan menghasilkan pesan error. Anda dapat melihat pesan error ini dalam respons error. Sering kali, pesan error yang dihasilkan sistem mungkin tidak relevan dalam konteks produk Anda. Anda mungkin ingin menyesuaikan pesan error berdasarkan jenis error untuk membuat pesan lebih bermakna.

Untuk menyesuaikan pesan error, Anda dapat menggunakan aturan error atau kebijakan RaiseFault. Untuk informasi tentang perbedaan antara aturan error dan kebijakan RaiseFault, lihat FaultRules vs. kebijakan RaiseFault. Anda harus memeriksa kondisi menggunakan elemen Condition dalam aturan error dan kebijakan RaiseFault. Apigee menyediakan variabel error yang unik untuk setiap kebijakan dan nilai variabel error ditetapkan saat kebijakan memicu error runtime. Dengan menggunakan variabel ini, Anda dapat memeriksa kondisi error tertentu dan mengambil tindakan yang sesuai. Untuk informasi selengkapnya tentang cara memeriksa kondisi error, lihat Mem-build kondisi.

Tabel berikut menjelaskan variabel error khusus untuk kebijakan ini.

Variabel	Dari mana	Contoh
fault.name	fault.name dapat cocok dengan salah satu kesalahan yang tercantum dalam tabel Error runtime. Nama error adalah bagian terakhir dari kode error.	fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed	POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menampilkan error.	IntegrationCallout.integration-callout-1.failed = true

Untuk informasi selengkapnya tentang error kebijakan, lihat Yang perlu Anda ketahui tentang error kebijakan.

Topik terkait

Jika Anda ingin mempelajari lebih lanjut fitur Application Integration, lihat Ringkasan Application Integration