Kebijakan ExternalInfo

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Apa

Dengan kebijakan ExternalCallout, Anda dapat 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 flow 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 tetapkan 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 memodifikasi variabel seperti yang ditetapkan dalam kode. Selanjutnya, server gRPC akan mengirimkan 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 dimodifikasi, variabel tersebut akan diperbarui di Apigee.

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua pengguna perlu mengetahui tentang kebijakan dan jenis lingkungan. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.

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

• gRPC
• Buffering Protokol

<ExternalCallout>

Menentukan kebijakan ExternalCallout.

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

Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:

Tabel berikut menjelaskan elemen turunan <ExternalCallout>.

Contoh 1

Contoh penggunaan ExternalCallout tersedia di Contoh Info 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 mengirimkan permintaan ke server gRPC eksternal yang diwakili oleh TargetServer bernama external-target-server, dengan konfigurasi berikut:

• <Property>: Menyertakan konten permintaan dan respons, tetapi bukan header permintaan dan respons, dalam permintaan yang dikirim ke server gRPC.
• <FlowVariable>: Menyertakan variabel flow 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 ditetapkan 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 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 bilangan positif.

<GrpcConnection>

Elemen <GrpcConnection> menetapkan server gRPC menjadi TargetServer yang sudah 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 yang bernama external-target-server.

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

Tabel berikut menjelaskan elemen turunan <GrpcConnection>.

Elemen <Server>

Menentukan server gRPC.

Tabel berikut menjelaskan atribut elemen <Server>.

Elemen <Authentication>

Menghasilkan 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 artikel Menggunakan autentikasi Google. Dengan penyiapan yang benar, kebijakan akan membuat token autentikasi untuk Anda dan menambahkannya ke permintaan layanan.

Elemen ini memiliki satu elemen turunan yang diperlukan: GoogleIDToken.

Elemen Authentication menggunakan sintaksis berikut:

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

<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, ketika ada konfigurasi Authentication, Apigee akan menghasilkan token pemilik 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.

Elemen HeaderName menggunakan sintaksis berikut:

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

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

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

Elemen GoogleIDToken menggunakan sintaksis berikut:

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

<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 dapat diakses oleh token tersebut.

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

Secara default, useTargetUrl bernilai 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'/>

Elemen turunan <IncludeEmail>

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

<Configurations>

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

Tabel berikut menjelaskan elemen turunan <Configurations>.

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

<FlowVariable>

Elemen <FlowVariable> menentukan variabel alur tambahan apa saja 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

Deployment of \"organizations/foo/apis/apiproxy/revisions/1\"
requires a service account identity, but one was not provided
with the request.

Error runtime

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

{
  "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"
    }
  }
}

Error lain-lain

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

Retakan

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

Topik terkait

• Kebijakan JavaCallout