Kebijakan ExternalCallout

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

ikon kebijakan

Apa

Kebijakan ExternalCallout memungkinkan Anda mengirim permintaan gRPC ke server gRPC untuk menerapkan perilaku kustom yang tidak didukung oleh kebijakan Apigee. Dalam kode server, Anda dapat dengan mudah mengakses dan mengubah variabel alur dalam alur proxy.

Apigee berkomunikasi dengan server gRPC melalui kebijakan ExternalCallout melalui API. Apigee menggunakan API untuk mengirim variabel alur ke server gRPC. Dalam server gRPC, Anda dapat membaca—dan bergantung pada variabel, mengubah— variabel alur yang tercantum di halaman referensi Variabel alur, serta variabel tambahan yang Anda tentukan dalam XML kebijakan.

Jika Anda mengonfigurasi server gRPC dengan Apigee dan menyertakan kebijakan ini dalam proxy, Apigee akan menangani permintaan API sebagai berikut:

  1. Apigee mengirim pesan yang berisi variabel alur ke server gRPC Anda.
  2. Kode server gRPC Anda dieksekusi, mengakses dan mengubah variabel seperti yang ditentukan dalam kode. Server gRPC kemudian mengirim respons yang berisi semua variabel alur kembali ke Apigee.
  3. Apigee membaca respons dari server gRPC Anda. Jika ada variabel yang ditambahkan atau variabel alur yang dapat diubah diubah, variabel tersebut akan diperbarui di Apigee.

Kebijakan ini adalah kebijakan Standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Untuk mempelajari lebih lanjut cara mengirim permintaan gRPC, lihat link berikut:

<ExternalCallout>

Menentukan kebijakan ExternalCallout.

<ExternalCallout async="true" continueOnError="true" enabled="true" name="EC">

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

Tabel berikut menjelaskan elemen turunan dari <ExternalCallout>.

Elemen Turunan Wajib Deskripsi
<TimeoutMs> Wajib Waktu tunggu permintaan dalam milidetik untuk permintaan gRPC.
<GrpcConnection> Wajib Menentukan nama TargetServer yang ada sebagai server gRPC yang akan menerima permintaan.
<Configurations> Opsional Memungkinkan Anda mengonfigurasi berbagai aspek kebijakan ExternalCallout, termasuk elemen <Property> dan <FlowVariable>.

Contoh 1

Contoh kerja ExternalCallout tersedia di External Callout Samples di GitHub.

Contoh berikut mengilustrasikan konfigurasi kebijakan ExternalCallout.

<ExternalCallout enabled="true" continueOnError="false" name="ExternalCallout-1">
  <DisplayName>External Callout 1</DisplayName>
  <TimeoutMs>5000</TimeoutMs>
  <GrpcConnection>
    <Server name="external-target-server"/>
  </GrpcConnection>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">false</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">false</Property>
    <FlowVariable>example1.flow.variable</FlowVariable>
    <FlowVariable>example2.flow.variable</FlowVariable>
  </Configurations>
<ExternalCallout>

Contoh ini mengirim permintaan ke server gRPC eksternal yang diwakili oleh TargetServer bernama external-target-server, dengan konfigurasi berikut:

  • <Property>: Sertakan konten permintaan dan respons, tetapi tidak header permintaan dan respons, dalam permintaan yang dikirim ke server gRPC.
  • <FlowVariable>: Sertakan variabel alur example1.flow.variable dan example2.flow.variable tambahan, yang ditentukan oleh elemen FlowVariable, dalam permintaan yang dikirim ke server gRPC.

Contoh 2

Dalam contoh berikut, atribut useTargetUrl dari elemen Audience disetel ke true. Jika useTargetUrl adalah true, nama host server target gRPC digunakan sebagai audiens. Misalnya, jika host server adalah my-grpc-server-java.a.run.app, maka audiens yang digunakan adalah https://my-grpc-server-java.a.run.app.

<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1">
  <DisplayName>External-Callout-1</DisplayName>
  <GrpcConnection>
    <Server name="cloud_run_server_name"/>
    <Authentication>
      <GoogleIDToken>
        <Audience useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
  </GrpcConnection>
  <TimeoutMs>5000</TimeoutMs>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">true</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">true</Property>
    <FlowVariable>example.flow.variable</FlowVariable>
    <FlowVariable>another.flow.variable</FlowVariable>
  </Configurations>
</ExternalCallout>

Referensi elemen turunan

Bagian berikut menjelaskan elemen turunan ExternalCallout.

<TimeoutMs>

Waktu tunggu permintaan dalam milidetik untuk permintaan gRPC. <TimeoutMs> harus berupa bilangan positif.

<GrpcConnection>

Elemen <GrpcConnection> menetapkan server gRPC sebagai TargetServer yang ada, yang ditentukan oleh atribut name. Lihat halaman referensi resource TargetServer.

Catatan: protokol untuk TargetServer harus GRPC.

Misalnya, kode berikut

<GrpcConnection>
  <Server name="external-target-server"/>
</GrpcConnection>

menentukan server gRPC sebagai TargetServer bernama external-target-server.

Gunakan elemen <Authentication> (dijelaskan nanti di bagian ini) untuk membuat token OpenID Connect yang dikeluarkan Google untuk melakukan panggilan terautentikasi ke layanan berbasis gRPC, seperti layanan kustom yang dihosting di Cloud Run.

Tabel berikut menjelaskan elemen turunan dari <GrpcConnection>.

Elemen Turunan Wajib? Deskripsi
Elemen <Server> Wajib Menentukan server gRPC.
Elemen <Authentication> Opsional Membuat token OpenID Connect yang dikeluarkan Google untuk melakukan panggilan terautentikasi ke layanan berbasis gRPC, seperti Cloud Run.

Elemen <Server>

Menentukan server gRPC.

Tabel berikut menjelaskan atribut elemen <Server>.

Atribut Deskripsi Default Kehadiran Jenis
name

Nama TargetServer yang ada untuk menjadi server gRPC yang akan dikirimi permintaan.

 T/A Wajib String

Elemen <Authentication>

Membuat token OpenID Connect yang dikeluarkan Google untuk melakukan panggilan terautentikasi ke layanan berbasis gRPC, seperti layanan kustom yang dihosting di Cloud Run. Penggunaan elemen ini memerlukan langkah penyiapan dan deployment yang dijelaskan dalam Menggunakan autentikasi Google. Dengan penyiapan yang tepat, kebijakan akan membuat token autentikasi untuk Anda dan menambahkannya ke permintaan layanan.

Elemen ini memiliki satu elemen turunan wajib: GoogleIDToken.

Default T/A
Wajib? Opsional.
Jenis Jenis kompleks
Elemen Induk <GrpcConnection>
Elemen Turunan <GoogleIDToken>

Elemen Authentication menggunakan sintaksis berikut:

Sintaks

<ExternalCallout>
...
  <GrpcConnection>
    <Server name="cloud_run_server_name"/>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
         <Audience ref="variable-1">STRING</Audience>
         <IncludeEmail ref="variable-2">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </GrpcConnection>
</ExternalCallout>

Contoh

Contoh berikut menunjukkan elemen GoogleIDToken:

<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1">
  <DisplayName>External-Callout-1</DisplayName>
  <GrpcConnection>
     <Server name="cloud_run_server_name"/>
     <Authentication>
        <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
           <Audience>https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
  </GrpcConnection>
  <TimeoutMs>5000</TimeoutMs>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">true</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">true</Property>
    <FlowVariable>example.flow.variable</FlowVariable>
    <FlowVariable>another.flow.variable</FlowVariable>
  </Configurations>
</ExternalCallout>
Atribut

Tidak ada.

Elemen turunan <HeaderName>

Secara default, jika konfigurasi Autentikasi ada, Apigee akan membuat token bearer dan menyisipkannya ke header Authorization dalam pesan yang dikirim ke sistem target. Elemen HeaderName memungkinkan Anda menentukan nama header lain untuk menyimpan token bearer tersebut. Fitur ini sangat berguna saat targetnya adalah layanan Cloud Run yang menggunakan header X-Serverless-Authorization. Header Authorization, jika ada, tidak diubah dan juga dikirim dalam permintaan.

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

Elemen HeaderName menggunakan sintaksis berikut:

Sintaks

<ExternalCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleIDToken>
    ... 
    </GoogleIDToken>
  </Authentication>
  ...
</ExternalCallout>

Dengan string statis

Dalam contoh ini, token pembawa yang dihasilkan ditambahkan, secara default, ke header bernama X-Serverless-Authorization yang dikirim ke sistem target. Header Authorization, jika ada, tidak diubah dan juga dikirim dalam permintaan.

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleIDToken>
    <Audience>https://cloudrun-hostname.a.run.app</Audience>
  </GoogleIDToken>
</Authentication>

Dengan referensi variabel

Dalam contoh ini, token pembawa yang dihasilkan ditambahkan, secara default, ke header bernama X-Serverless-Authorization yang dikirim ke sistem target. Jika my-variable memiliki nilai, nilai tersebut akan digunakan, bukan string default. Header Authorization, jika ada, tidak diubah dan juga dikirim dalam permintaan.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleIDToken>
    <Audience>https://cloudrun-hostname.a.run.app</Audience>
  </GoogleIDToken>
</Authentication>
Elemen turunan <GoogleIDToken>

Membuat token OpenID Connect yang dikeluarkan Google untuk melakukan panggilan terautentikasi ke layanan Google, seperti layanan kustom yang dihosting di Cloud Run.

Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <Authentication>
Elemen Turunan <Audience>
<IncludeEmail>

Elemen GoogleIDToken menggunakan sintaksis berikut:

Sintaks

<ExternalCallout>
...
  <GrpcConnection>
    <Server name="cloud_run_server_name"/>
    <Authentication>
      <GoogleIDToken>
        <Audience ref="context-variable" useTargetUrl='BOOLEAN'>STRING</Audience>
        <IncludeEmail ref="context-variable">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </GrpcConnection>
</ExternalCallout>

Contoh

Contoh berikut menunjukkan elemen GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>
Elemen turunan <Audience>

Audiens untuk token autentikasi yang dibuat, seperti API atau akun yang diberi akses oleh token.

Jika nilai Audience kosong, ref kosong atau di-resolve ke nilai kosong, dan useTargetUrl adalah true, maka "https://" + (nama host server target gRPC) digunakan sebagai audiens. Misalnya, jika host server adalah my-grpc-server-java.a.run.app, maka audiens yang digunakan adalah https://my-grpc-server-java.a.run.app.

Secara default, useTargetUrl adalah false.

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>
Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <GoogleIDToken>
Elemen Turunan Tidak ada.
Elemen turunan <IncludeEmail>

Jika disetel ke true, token autentikasi yang dihasilkan akan berisi klaim email dan email_verified akun layanan.

Default false
Wajib? Opsional
Jenis Boolean
Elemen Induk <GoogleIDToken>
Elemen Turunan Tidak ada.

<Configurations>

Elemen <Configurations> memungkinkan Anda mengonfigurasi berbagai aspek kebijakan ExternalCallout, termasuk <Property> dan <FlowVariable>.

Tabel berikut menjelaskan elemen turunan dari <Configurations>.

Elemen Turunan Wajib? Deskripsi
<Property> Wajib

Menentukan apakah header dan/atau konten permintaan/respons akan dikirim ke server. Kemungkinan nilainya adalah true atau false. Defaultnya adalah false.

<FlowVariable> Wajib

Menentukan variabel alur tambahan yang harus dikirim ke server.

<Property>

Elemen <Property> menentukan apakah header dan/atau konten permintaan/respons akan dikirim ke server. Nilai yang mungkin adalah true (item akan dikirim) atau false (item tidak akan dikirim). Nilai defaultnya adalah false.

Tabel berikut menjelaskan atribut elemen <Property>.

Atribut Deskripsi Default Kehadiran Jenis
name

Menentukan konten apa yang akan dikirim ke server. Nilai yang mungkin untuk name adalah:

  • with.request.content
  • with.request.headers
  • with.response.content
  • with.response.headers
 T/A Wajib String

<FlowVariable>

Elemen <FlowVariable> menentukan variabel alur tambahan yang akan dikirim ke server. Nilai <FlowVariable> adalah awalan variabel, bukan nama variabel lengkap. Misalnya , jika elemen adalah a.b.c, nilai variabel bernama a.b.c akan dikirim ke server. Demikian pula, nilai variabel bernama a.b.c.my-variable akan dikirim ke server. Namun, nilai variabel bernama a.x.another-variable tidak akan dikirim, karena tidak memiliki prefiks a.b.c. Berikut beberapa contohnya

<Configurations>
  <FlowVariable>a.b.c</FlowVariable>
  <FlowVariable>d.e.f</FlowVariable>
</Configurations>

Referensi Error

Error saat deployment

Nama error Penyebab
FAILED_PRECONDITION Error ini terjadi jika akun layanan tidak ada saat proxy dikonfigurasi dengan tag <Authentication>.

Contoh: 

Deployment of \"organizations/foo/apis/apiproxy/revisions/1\"
requires a service account identity, but one was not provided
with the request.
PERMISSION_DENIED Error ini terjadi jika ada masalah izin dengan akun layanan jika proxy dikonfigurasi dengan tag <Authentication>. Kemungkinan penyebab:
  • Akun layanan tidak ada.
  • Akun layanan tidak dibuat di project Google Cloud yang sama dengan organisasi Apigee.
  • Deployer memiliki izin iam.serviceAccounts.actAs di akun layanan. Untuk mengetahui detailnya, lihat Tentang izin akun layanan.

Error runtime

Tabel di bawah menjelaskan error runtime, yang dapat terjadi saat kebijakan dijalankan.

Kode kesalahan Status HTTP Penyebab
GrpcTlsInitFailed 500

Error ini akan terjadi jika ada masalah saat menginisialisasi TLS dengan server gRPC (seperti masalah Keystore atau truststore).
steps.externalcallout.[error_code] 500

[error_code] ditentukan oleh kolom errorCode pesan Fault. String kesalahan akan menjadi kolom faultstring pesan kesalahan.
steps.externalcallout.ExecutionError 500

Error ini akan terjadi jika ada pengecualian lain selama eksekusi kebijakan ini. Pengecualian yang mendasarinya akan ditampilkan dalam faultstring. Jika ada masalah dengan kredensial ke server gRPC, error akan terlihat seperti ini:

{
  "fault": {
    "faultstring": "Encountered the following exception while sending the gRPC request or
     processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed
     to obtain metadata].",
    "detail": {
      "errorcode": "steps.externalcallout.ExecutionError"
    }
  }
}

Anda dapat melihat log MP untuk mendapatkan petunjuk penelusuran bug lebih lanjut.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> diaktifkan, tetapi useTargetUrl disetel ke salah dan tidak ada nilai yang diberikan ke <Audience> baik secara langsung atau melalui referensi pada saat terjadi error.
steps.externalcallout.ExecutionError

dengan string kesalahan:

Encountered the following exception while sending the gRPC request or processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed to obtain metadata]

 500

Error ini terjadi jika proxy API dikonfigurasi dengan elemen <Authentication>. Penyebab yang mungkin:

  • Akun layanan yang di-deploy dengan proxy:
    • tidak ada di project Anda (ada saat di-deploy, tetapi dihapus setelah deployment)
    • telah dinonaktifkan
    • (Khusus Apigee Hybrid) belum memberikan peran roles/iam.serviceAccountTokenCreator di akun layanan apigee-runtime.
  • (Khusus Apigee hybrid) API IAMCredentials dinonaktifkan di project sumber akun layanan apigee-runtime.

    Catatan: Khusus untuk Apigee Hybrid, periksa log penampung runtime dan telusuri externalcallout.ExecutionError untuk menemukan pesan error yang lebih mendetail yang dapat membantu men-debug masalah.

steps.externalcallout.ExecutionError dengan faultstring yang berisi PERMISSION DENIED.

Misalnya, faultstring akan terlihat seperti berikut untuk Cloud Run:

Encountered the following exception while sending the gRPC request or processing the response: [io.grpc.StatusRuntimeException: PERMISSION_DENIED: HTTP status code 403 …]

 500

Error ini terjadi jika proxy API dikonfigurasi dengan elemen <Authentication>. Penyebab yang mungkin:

  • Akun layanan proxy ada dan diaktifkan, tetapi tidak memiliki izin yang tepat untuk mengakses layanan.
  • Layanan memerlukan autentikasi, tetapi permintaan tidak memiliki header autentikasi (Misalnya: XML autentikasi tidak disertakan dalam XML kebijakan).

Error lain-lain

Tabel di bawah ini menjelaskan berbagai error. Lihat penyebabnya untuk mengetahui detail selengkapnya.

Kode kesalahan Penyebab
ReferencesExistToGrpcServer

Error ini akan terjadi jika pengguna mencoba menghapus server target gRPC, tetapi server masih digunakan oleh kebijakan lain.

Kesalahan

Variabel kesalahan dalam tabel berikut ditetapkan untuk semua kebijakan secara default. Lihat Variabel khusus untuk error kebijakan.

Variabel Di mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Kesalahan runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name cocok dengan "ExecutionError".
externalcallout.[policy_name].failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menyebabkan kesalahan. externalcallout.ExternalCallout-1.failed = true

Topik terkait