Kebijakan IntegrationCallout

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

ikon kebijakan

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.

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

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <IntegrationCallout>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<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

This section describes the fault codes, error messages, and the fault variables set by Apigee when this policy triggers an error. This information is essential if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
entities.UnresolvedVariable 500 This error occurs if Apigee cannot resolve the integration.project.id or the integration.name variables.
steps.integrationcallout.ExecutionFailed 500

This error can occur if the backend target service returns an HTTP error status such as 4xx or 5xx. The possible causes include:

  • The service account deployed with the proxy has the incorrect permissions to run the integration.
  • The integration or the API trigger does not exist.
  • Application Integration is not enabled for your Google Cloud project.
  • You have configured the <ScheduleTime> element in your SetIntegrationRequest policy and the IntegrationCallout policy has the AsyncExecution set to false.
steps.integrationcallout.NullRequestVariable 500 This error occurs if the flow variable specified in the <Request> is null.
steps.integrationcallout.RequestVariableNotMessageType 500 This error occurs when the flow variable specified by the Request element is not of message type.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 This error occurs when the flow variable specified by the Request element is not of Request message type.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

This error can occur because of an incorrect service account configuration. The possible causes include:

  • The service account deployed with the proxy does not exist in your project.
  • The service account deployed with the proxy is disabled.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

The following table describes the fault variables specific to this policy.

Variables Where Example
fault.name The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME is the user-specified name of the policy that threw the fault. IntegrationCallout.integration-callout-1.failed = true
For more information about policy errors, see What you need to know about policy errors.

Topik terkait

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