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 mengirimkan pesan yang berisi variabel alur ke server gRPC Anda.
  2. Kode server gRPC Anda mengeksekusi, 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 variabel 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 kebijakan dan ketersediaan 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 sama 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.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
continueOnError false Opsional 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. Lihat juga:
enabled true Opsional Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.
async   false Tidak digunakan lagi Atribut ini sudah 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 Contoh Callout Eksternal 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>: Menyertakan konten permintaan dan respons, tetapi tidak menyertakan header permintaan dan respons, dalam permintaan yang dikirim ke server gRPC.
  • <FlowVariable>: Menyertakan variabel alur tambahan example1.flow.variable dan example2.flow.variable, 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 akan digunakan sebagai audiens. Misalnya, jika host server adalah my-grpc-server-java.a.run.app, audiens yang digunakan akan menjadi 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 menjadi 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 menjadi TargetServer yang ada 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 menerima permintaan.

 T/A Wajib String

Elemen <Authentication>

Membuat token OpenID Connect yang diterbitkan Google untuk melakukan panggilan terautentikasi ke layanan berbasis gRPC, seperti layanan kustom yang dihosting di Cloud Run. Penggunaan elemen ini memerlukan langkah-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 yang diperlukan: 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 pembawa dan memasukkannya ke header Authorization dalam pesan yang dikirim ke sistem target. Elemen HeaderName memungkinkan Anda menentukan nama header yang berbeda untuk menyimpan token pembawa tersebut. Fitur ini sangat berguna jika 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>

Menghasilkan token OpenID Connect yang diterbitkan 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 dihasilkan, seperti API atau akun yang diberi akses oleh token.

Jika nilai Audience kosong, ref kosong atau me-resolve ke nilai kosong, dan useTargetUrl adalah true, maka "https://" + (nama host server target gRPC) akan digunakan sebagai audiens. Misalnya, jika host server adalah my-grpc-server-java.a.run.app, audiens yang digunakan akan menjadi 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 ditetapkan 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 permintaan/respons dan/atau konten 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 permintaan/respons dan/atau konten akan dikirim ke server. Kemungkinan nilainya 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 yang akan dikirim ke server. Kemungkinan nilai 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 awalan 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 dieksekusi.

Kode kerusakan Status HTTP Penyebab
GrpcTlsInitFailed 500

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

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

Error ini akan terjadi jika ada pengecualian lain yang terjadi 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 mengetahui petunjuk proses debug lebih lanjut.
googletoken.EmptyIDTokenAudience 500

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

dengan string error:

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) IAMCredentials API 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 proses 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 lainnya

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

Kode kerusakan Penyebab
ReferencesExistToGrpcServer

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

Fault

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

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama kerusakan adalah bagian terakhir dari kode kerusakan. fault.name cocok dengan "ExecutionError".
externalcallout.[policy_name].failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. externalcallout.ExternalCallout-1.failed = true

Topik terkait