Kebijakan InfoLayanan

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

ikon kebijakan

Apa

Kebijakan ServiceInfo memungkinkan Anda memanggil layanan lain dari alur proxy API. Anda dapat membuat pemanggilan ke layanan eksternal (seperti endpoint layanan RESTful eksternal) atau layanan internal (seperti proxy API dalam organisasi dan lingkungan yang sama).

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

  • Dalam kasus penggunaan eksternal, Anda membuat pemanggilan ke API pihak ketiga yang berada di luar cakupan {i>proxy<i}. Respons dari API pihak ketiga akan diuraikan dan disisipkan dalam respons API Anda pesan, memperkaya dan menggabungkan data untuk pengguna akhir aplikasi. Anda juga dapat mengajukan permintaan menggunakan kebijakan ServiceInfo dalam alur permintaan, lalu meneruskan informasi tersebut dalam respons ke TargetEndpoint proxy API.
  • Dalam kasus penggunaan lain, Anda memanggil {i>proxy<i} yang ada di organisasi dan lingkungan yang sama dengan nomor yang Anda gunakan. Misalnya, Anda mungkin menemukan bahwa ini berguna ketika Anda memiliki {i>proxy<i} yang menawarkan beberapa fungsionalitas tingkat rendah yang akan digunakan oleh satu atau lebih {i>proxy<i} lainnya. Sebagai contoh, proxy yang mengekspos operasi buat/baca/perbarui/hapus dengan penyimpanan data backend dapat menjadi {i>proxy<i} target untuk beberapa {i>proxy<i} lainnya yang mengekspos data ke klien.

Kebijakan ini mendukung permintaan melalui HTTP dan HTTPS.

Contoh

Panggilan lokal ke proxy internal

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Contoh ini membuat pemanggilan ke proxy API lokal (yaitu, satu proxy di organisasi yang sama dan lingkungan) yang disebut data-manager, yang menentukan endpoint proxy yang namanya adalah default.

URL sebagai variabel

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

Contoh ini menggunakan variabel dalam URL untuk mengisi URL target secara dinamis. Tujuan bagian protokol dari URL, http://, tidak dapat ditentukan oleh variabel. Selain itu, Anda harus menggunakan variabel terpisah untuk bagian domain dari URL dan untuk bagian URL lainnya.

Geocoding / definisi permintaan Google

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Daripada menggunakan kebijakan seperti kebijakan TetapkanMessage untuk membuat objek permintaan, Anda dapat menentukannya langsung di kebijakan Servicecallout. Dalam contoh ini, kebijakan ServiceInfo menetapkan nilai dari tiga parameter kueri yang diteruskan ke layanan eksternal. Anda dapat membuat seluruh pesan permintaan dalam kebijakan Servicecallout yang menentukan payload, jenis encoding seperti application/xml, header, parameter formulir, dll.

Berikut adalah contoh lain saat permintaan dibuat sebelum mencapai ServiceInfo lebih lanjut.

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Isi pesan permintaan diekstrak dari variabel yang disebut GeocodingRequest (yang dapat berupa diisi, misalnya, oleh kebijakan MenetapkanMessage). Pesan respons ditugaskan ke variabel yang disebut GeocodingResponse, yang merupakan tersedia untuk diuraikan oleh kebijakan ExtractVariables atau dengan kode kustom yang ditulis dalam JavaScript atau Java. Kebijakan tersebut menunggu 30 detik untuk respons dari Google Geocoding API sebelum waktu habis.

Server target panggilan

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

Kebijakan ini menggunakan atribut LoadBalancer untuk memanggil server target dan melakukan load balancing di seluruh mereka. Dalam contoh ini, beban didistribusikan ke dua server target yang bernama httpbin dan yahoo. Untuk informasi tentang cara menyiapkan Server Target untuk proxy Anda dan mengonfigurasi load balancing, lihat Load balancing di seluruh server backend.

Tentang kebijakan ServiceInfo

Ada banyak skenario saat Anda dapat menggunakan kebijakan ServiceInfo di proxy API Anda. Sebagai Anda bisa mengonfigurasi proxy API untuk melakukan panggilan ke layanan eksternal guna mengirim data geolokasi, ulasan pelanggan, item dari katalog retail partner, dan sebagainya.

Info biasanya digunakan dengan dua kebijakan lain: MenetapkanMessage dan ExtractVariables.

  • Permintaan: Menetapkan Pesan mengisi pesan permintaan yang dikirim ke remote layanan.

  • Response: ExtractVariables menguraikan respons dan mengekstraksi respons saat ini.

Komposisi kebijakan ServiceKeterangan standar mencakup:

  1. Kebijakan MenetapkanMessage: Membuat pesan permintaan, mengisi header HTTP, parameter kueri, menetapkan HTTP verba, dll.

  2. Kebijakan ServiceInfo: Mereferensikan pesan yang dibuat oleh MenetapkanMessage kebijakan, menentukan URL target untuk panggilan eksternal, dan menentukan nama untuk objek respons yang ditampilkan oleh layanan target.

    Untuk meningkatkan performa, Anda juga dapat meng-cache respons ServiceInfo, seperti yang dijelaskan dalam Bagaimana cara menyimpan hasil kebijakan ServiceInfo dalam cache? lalu mengambilnya dari cache?

  3. Kebijakan ExtractVariables: Biasanya menentukan ekspresi JSONPath atau XPath yang mengurai pesan yang dihasilkan oleh ServiceInfo. Kebijakan ini kemudian menetapkan variabel yang berisi nilai yang diuraikan dari Respons ServiceInfo.

Penanganan error kustom

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi di kebijakan ini:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

&lt;ServiceCallout&gt; atribut

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:

Atribut Deskripsi Default Kehadiran
name

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.

 T/A Diperlukan
continueOnError

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:

 false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.

 true Opsional
async

Atribut ini sudah tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

&lt;Request&gt; elemen

Menentukan variabel berisi pesan permintaan yang dikirimkan dari proxy API ke layanan lainnya. Variabel dapat dibuat oleh kebijakan sebelumnya dalam alur, atau Anda dapat membuatnya inline dalam kebijakan Servicecallout.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

Sintaksis untuk tag <Remove>, <Copy>, <Add>, dan <Set> sama dengan sintaksis untuk AssignMessage kebijakan kami.

Kebijakan ini akan menampilkan error jika pesan permintaan tidak dapat diselesaikan atau tidak valid jenis pesan permintaan.

Dalam contoh yang paling sederhana, Anda meneruskan variabel yang berisi pesan permintaan yang telah diisi sebelumnya dalam alur proxy API:

<Request clearPayload="true" variable="myRequest"/>

Atau, Anda dapat mengisi pesan permintaan yang dikirim ke layanan eksternal dalam kebijakan ServiceInfo itu sendiri:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Default Jika Anda menghapus elemen Request, atau salah satu atributnya, Apigee akan menetapkan nilai default berikut:

&lt;Request clearPayload=&quot;true&quot; variable=&quot;servicecallout.request&quot;/&gt;

Mari kita lihat arti nilai default ini. Pertama, clearPayload=true berarti bahwa objek permintaan dibuat setiap kali kebijakan Servicecallout dijalankan. Hal ini berarti bahwa permintaan dan jalur URI permintaan tidak pernah digunakan kembali. Kedua, variabel {i>default<i} nama, servicecallout.request, adalah nama yang dicadangkan yang ditetapkan ke permintaan jika Anda tidak memberikan nama.

Penting untuk mengetahui tentang nama {i>default<i} ini jika Anda menggunakan data masking -- jika Anda menghilangkan nama variabel, Anda perlu menambahkan servicecallout.request ke konfigurasi mask. Misalnya, jika Anda ingin menyamarkan header Otorisasi agar tidak muncul dalam sesi Debug, Anda akan menambahkan hal berikut ke konfigurasi penyamaran untuk mengambil nama default:

servicecallout.request.header.Authorization.
Kehadiran Opsional.
Jenis T/A

Atribut

Atribut Deskripsi Default Kehadiran
variabel

Nama variabel yang akan berisi pesan permintaan.

 servicecallout.request Opsional
clearPayload

Jika true, variabel yang berisi pesan permintaan akan dihapus setelah dikirim ke target HTTP untuk mengosongkan memori yang digunakan oleh pesan permintaan.

Setel clearPayload menjadi false hanya jika pesan permintaan diperlukan setelah ServiceInfo telah dijalankan.

 benar Opsional

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; elemen

Jika disetel ke true, kebijakan mengabaikan error variabel yang belum terselesaikan dalam permintaan.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Default salah
Kehadiran Opsional
Jenis Boolean

&lt;Response&gt; elemen

Sertakan elemen ini ketika logika proxy API memerlukan respons dari panggilan jarak jauh untuk diproses lebih lanjut.

Jika ada, elemen ini menentukan nama variabel yang akan berisi pesan respons yang diterima dari layanan eksternal. Respons dari target ditugaskan kepada variabel hanya ketika seluruh respons berhasil dibaca oleh kebijakan. Jika panggilan jarak jauh gagal karena alasan apa pun, kebijakan akan menampilkan error.

Jika elemen ini dihilangkan, proxy API tidak menunggu respons; Alur Proxy API dan eksekusi akan dilanjutkan dengan langkah-langkah alur berikutnya. Juga, untuk menyatakan hal yang sudah jelas, tanpa Response, respons dari target tidak tersedia untuk diproses oleh langkah selanjutnya, dan tidak ada cara bagi alur proxy untuk mendeteksi kegagalan dalam panggilan jarak jauh. Penggunaan umum untuk menghilangkan elemen Response saat menggunakan Servicecallout: untuk mencatat pesan ke sistem eksternal.

 <Response>calloutResponse</Response>
Default NA
Kehadiran Opsional
Jenis String

<Waktu tunggu> elemen

Waktu dalam milidetik saat kebijakan ServiceInfo akan menunggu respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika ServiceInfo mencapai waktu tunggu, HTTP 500 dikembalikan, kebijakan gagal, dan proxy API masuk ke status kesalahan, yang dijelaskan dalam Menangani kesalahan.

<Timeout>30000</Timeout>
Default 55.000 milidetik (55 detik), setelan waktu tunggu HTTP default untuk Apigee
Kehadiran Opsional
Jenis Bilangan bulat

&lt;HTTPTargetConnection&gt; elemen

Memberikan detail transpor seperti properti URL, TLS/SSL, dan HTTP. Lihat Referensi konfigurasi <TargetEndpoint>.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
Default T/A
Kehadiran Wajib
Jenis T/A

&lt;HTTPTargetConnection&gt;/&lt;Authentication&gt; elemen

Membuat Google OAuth 2.0 atau token OpenID Connect yang dikeluarkan Google untuk melakukan panggilan terautentikasi ke layanan Google dan layanan kustom yang sedang berjalan pada produk Google Cloud tertentu, seperti Cloud Functions dan Cloud Run. Penggunaan elemen ini memerlukan langkah-langkah penyiapan dan deployment yang dijelaskan dalam Menggunakan autentikasi Google. Dengan penyiapan yang tepat, kebijakan tersebut akan membuat token autentikasi untuk Anda dan menambahkannya ke permintaan layanan.

Elemen turunan, GoogleAccessToken dan GoogleIDToken, memungkinkan Anda mengonfigurasi kebijakan untuk menghasilkan token Google OAuth atau OpenID Connect. Anda harus memilih salah satu elemen turunan ini, bergantung pada jenis layanan yang ingin Anda panggil.

Kebijakan ServiceInfo hanya mendukung pemanggilan layanan berbasis HTTP.

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

Elemen Authentication menggunakan sintaksis berikut:

Sintaks

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

Menggunakan GoogleAccessToken

Contoh berikut menunjukkan elemen GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Menggunakan GoogleIDToken

Contoh berikut menunjukkan elemen GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Menggunakan HeaderName

Contoh berikut menunjukkan elemen HeaderName:

  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

Menggunakan LifetimeInSeconds

Contoh berikut menunjukkan elemen HeaderName:

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

Atribut

Tidak ada.

Elemen turunan HeaderName

Secara default, saat konfigurasi Autentikasi tersedia, Apigee membuat pemilik token dan memasukkannya ke dalam header Authorization dalam pesan yang dikirim ke sistem target. Elemen HeaderName memungkinkan Anda menentukan nama header yang berbeda untuk menyimpan token pembawa itu. Fitur ini sangat berguna jika targetnya adalah Cloud Run layanan yang menggunakan header X-Serverless-Authorization. Header Authorization, jika ada, tidak akan 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

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Dengan string statis

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

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Dengan referensi variabel

Dalam contoh ini, token pemilik yang dihasilkan akan ditambahkan secara default ke header bernama X-Serverless-Authorization yang dikirim ke sistem target. Jika my-variable memiliki nilai, nilai tersebut akan digunakan bukannya menggunakan {i>string<i} {i>default<i}. Header Authorization, jika ada, tidak akan diubah dan juga dikirim dalam permintaan.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Elemen turunan GoogleAccessToken

Membuat token Google OAuth 2.0 untuk melakukan panggilan terautentikasi ke layanan Google. Token Google OAuth dapat digunakan untuk memanggil berbagai jenis layanan Google, seperti Cloud Logging dan Secret Manager.

Default T/A
Wajib? Elemen turunan GoogleAccessToken atau GoogleIDToken harus ada.
Jenis String
Elemen Induk <Authentication>
Elemen Turunan <Scopes>
<LifetimeInSeconds>

Elemen GoogleAccessToken menggunakan sintaksis berikut:

Sintaks

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Contoh 1

Contoh berikut menunjukkan elemen GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Contoh 2

Contoh berikut menunjukkan cara terhubung ke secret manager untuk mengambil secret menggunakan kebijakan ServiceInfo. 

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>

Contoh 3

Contoh berikut menunjukkan cara membuat pemanggilan ke Cloud yang dijalankan dari kebijakan Servicecallout. 

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Cakupan elemen turunan

Mengidentifikasi cakupan yang akan disertakan dalam token akses OAuth 2.0. Untuk informasi selengkapnya, lihat Cakupan OAuth 2.0 untuk Google API. Anda dapat menambahkan satu atau beberapa elemen turunan <Scope> di bawah elemen ini.

Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <GoogleAccessToken>
Elemen Turunan <Scope>

Elemen turunan cakupan

Menentukan cakupan Google API yang valid. Untuk informasi selengkapnya, lihat Cakupan OAuth 2.0 untuk Google API.

Default T/A
Wajib? Diperlukan setidaknya 1 nilai.
Jenis String
Elemen Induk <Scopes>
Elemen Turunan Tidak ada.

Elemen turunan LifetimeInSeconds

Menentukan durasi masa aktif token akses dalam detik.

Default 3600
Wajib? Opsional
Jenis Bilangan bulat
Elemen Induk <GoogleAccessToken>
Elemen Turunan Tidak ada.

Elemen turunan GoogleIDToken

Menghasilkan token OpenID Connect yang dikeluarkan Google untuk melakukan panggilan terautentikasi ke layanan Google.

Default T/A
Wajib? Elemen turunan GoogleAccessToken atau GoogleIDToken harus ada.
Jenis String
Elemen Induk <Authentication>
Elemen Turunan <Audience>
<IncludeEmail>

Elemen GoogleIDToken menggunakan sintaksis berikut:

Sintaks

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

Contoh 1

Contoh berikut menunjukkan elemen GoogleIDToken:

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

Elemen turunan audiens

Audiens untuk token autentikasi yang dihasilkan, seperti API atau akun yang yang memberi akses token.

Jika nilai Audience kosong atau variabel ref tidak di-resolve menjadi nilai yang valid, dan useTargetUrl adalah true, lalu URL target (tidak termasuk parameter kueri) digunakan sebagai audiens. 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'/>
Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <GoogleIDToken>
Elemen Turunan Tidak ada.

Elemen turunan IncludeEmail

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

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; elemen

URL ke layanan yang dipanggil:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

Anda dapat menyediakan bagian URL secara dinamis dengan variabel. Namun, bagian protokol dari URL, http:// di bawah, tidak boleh yang ditentukan oleh variabel. Pada contoh berikutnya, Anda menggunakan variabel untuk menentukan nilai kueri :

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

Atau, tetapkan bagian jalur URL dengan variabel:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

Jika Anda ingin menggunakan variabel untuk menentukan domain dan port URL, gunakan satu variabel hanya untuk domain dan port, dan variabel kedua untuk bagian lain dari URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>
Default T/A
Kehadiran Wajib
Jenis String

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; elemen

Konfigurasi TLS/SSL ke layanan backend. Untuk bantuan tentang konfigurasi TLS/SSL, lihat Opsi untuk mengonfigurasi TLS dan "TLS/SSL TargetEndpoint Configuration" di referensi konfigurasi proxy API.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>
Default T/A
Kehadiran Opsional
Jenis T/A

&lt;HTTPTargetConnection&gt;/&lt;Properties&gt; elemen

Properti transpor HTTP ke layanan backend. Untuk informasi selengkapnya, lihat Referensi properti endpoint.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
Default T/A
Kehadiran Opsional
Jenis T/A

&lt;HTTPTargetConnection&gt;/&lt;LoadBalancer&gt; elemen

Panggil satu atau beberapa server target dan lakukan load balancing pada server tersebut. Lihat Target panggilan server di bagian Contoh. Lihat juga Load balancing di seluruh backend server. Lihat juga Info Endpoint/Server Target yang membahas cara memanggil server target dari kebijakan Service callout dan menggunakan Aturan Rute.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Default T/A
Kehadiran Opsional
Jenis T/A

&lt;LocalTargetConnection&gt; elemen

Menentukan proxy lokal -- yaitu, proxy dalam organisasi dan lingkungan yang sama -- seperti target info layanan.

Untuk menentukan target lebih lanjut, gunakan elemen <APIProxy> dan <ProxyEndpoint>, atau elemen <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
Default T/A
Kehadiran Wajib
Jenis T/A

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; elemen

Nama proxy API yang merupakan target panggilan lokal. Proxy harus sama organisasi dan lingkungan sebagai {i> proxy<i} yang melakukan panggilan.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Bersama dengan elemen <APIProxy>, sertakan <ProxyEndpoint> untuk menentukan nama endpoint proxy yang seharusnya ditargetkan untuk panggilan tersebut.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
Default T/A
Kehadiran Wajib
Jenis String

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; elemen

Nama endpoint proxy yang seharusnya menjadi target panggilan. Ini adalah titik akhir {i>proxy<i} di proxy API yang ditetapkan dengan elemen <APIProxy>.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
Default T/A
Kehadiran Opsional
Jenis T/A

&lt;LocalTargetConnection&gt;/&lt;Path&gt; elemen

Jalur ke endpoint yang ditarget. Endpoint harus merujuk ke proxy dalam organisasi dan lingkungan sebagai {i> proxy<i} yang melakukan panggilan.

Gunakan ini, bukan pasangan <APIProxy>/<ProxyEndpoint>, jika Anda tidak tahu -- atau tidak bisa mengandalkan -- nama {i>proxy<i}. Jalur ini mungkin merupakan target yang dapat diandalkan.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
Default T/A
Kehadiran Opsional
Jenis T/A

Skema

Variabel flow

Variabel flow memungkinkan perilaku dinamis kebijakan dan Flow saat runtime, berdasarkan HTTP header, konten pesan, atau konteks Alur. Variabel Flow yang telah ditentukan sebelumnya tersedia setelah kebijakan ServiceInfo dijalankan. Untuk informasi selengkapnya tentang variabel Flow, lihat Referensi variabel flow.

{i>Servicecallouts<i} memiliki permintaan dan responsnya sendiri, dan Anda dapat mengakses data tersebut melalui variabel. Karena pesan utama menggunakan request.* dan Awalan variabel response.*, gunakan myrequest.* dan Awalan calloutResponse.* (default di konfigurasi Servicecallout) menjadi mendapatkan data pesan khusus untuk Service callout. Contoh pertama dalam tabel berikut menunjukkan cara mendapatkan header HTTP di ServiceInfo.

Variabel Deskripsi

Berikut adalah contoh cara mendapatkan header respons dan permintaan ServiceInfo mirip dengan cara mendapatkan {i>header<i} dari permintaan dan respons utama.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

dengan calloutResponse adalah nama variabel untuk Respons di Layanan Keterangan, dan myRequest adalah nama variabel untuk Permintaan. Contoh:

calloutResponse.header.Content-Length

menampilkan header Content-Length dari respons Servicecallout.

Cakupan: Dari ServiceInfo berikutnya
Jenis: String
Izin: Baca/Tulis

Header pesan di permintaan atau respons Servicecallout. Misalnya, jika API target proxy adalah http://example.com, dan target ServiceInfo adalah http://mocktarget.apigee.net, variabel ini adalah header untuk pemanggilan http://mocktarget.apigee.net.
servicecallout.requesturi

Cakupan: Dari permintaan Service# selanjutnya
Jenis: String
Izin: Baca/Tulis

URI TargetEndpoint untuk kebijakan ServiceInfo. URI-nya adalah URL TargetEndpoint tanpa spesifikasi protokol dan domain.
servicecallout.{policy-name}.target.url

Cakupan: Dari permintaan Service# selanjutnya
Jenis: String
Izin: Baca/Tulis

URL target untuk ServiceInfo.

calloutResponse.content

dengan calloutResponse adalah nama variabel <Response> di konfigurasi ServiceInfo.

Cakupan: Dari respons ServiceInfo berikutnya
Jenis: String
Izin: Baca/Tulis

Isi respons dari ServiceInfo.
servicecallout.{policy-name}.expectedcn

Cakupan: Dari permintaan Service# selanjutnya
Jenis: String
Izin: Baca/Tulis

Nama Umum TargetEndpoint yang diharapkan sebagaimana dimaksud dalam ServiceKeterangan lebih lanjut. Ini hanya berguna jika TargetEndpoint merujuk ke TLS/SSL endpoint.
servicecallout.{policy-name}.failed

Cakupan: Dari respons ServiceInfo berikutnya
Jenis: Boolean
Izin: Baca/Tulis

Boolean yang menunjukkan apakah kebijakan berhasil, salah, atau gagal, benar (true).

Error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know 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 Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • The policy is asked to handle input that is malformed or otherwise invalid.
  • The backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type RequestMessage. For example, if it's a Response type, you'll see this error.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> is enabled but useTargetUrl is set to false and no value is provided to <Audience> either directly or through reference at the time of error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 This error can happen if the API proxy is configured with the <Authentication> element. Possible causes include:
  • The service account deployed with the proxy:
    • does not exist in your project
    • has been disabled
    • (Apigee hybrid only) has not granted the roles/iam.serviceAccountTokenCreator role on the apigee-runtime service account.
  • The IAMCredentials API is disabled in the source project of the apigee-runtime service account.
  • The <GoogleAccessToken> element is used and one or more invalid scopes are provided. For example, look for typos or empty scopes.

    • For Apigee hybrid only, check the runtime container's log and search for GoogleTokenGenerationFailure to find more detailed error messages that may help with debugging the problem.

    Deployment errors

    These errors can occur when you deploy a proxy containing this policy.

    Error name Cause Fix
    URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
    ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
    InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.
    FAILED_PRECONDITION This error happens if the service account is missing when the proxy is configured with the <Authentication> tag.

    For example: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED This error happens if there is a permission problem with the service account if the proxy is configured with the <Authentication> tag. Possible causes:
    • The service account does not exist.
    • The service account was not created in the same Google Cloud project as the Apigee organization.
    • The deployer does have iam.serviceAccounts.actAs permission on the service account. For details, see About service account permissions.

    Fault variables

    These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

    Variables Where Example
    fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

    Example error response

    {
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]:
            request variable data_str value is not of type Message"
   }
}

    Example fault rule

    <FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    Topik terkait