Kebijakan ServiceCallout

Kebijakan yang dapat diperluas

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

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

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.

  • Dalam kasus penggunaan eksternal, Anda membuat panggilan ke API pihak ketiga yang eksternal ke proxy Anda. Respons dari API pihak ketiga diuraikan dan dimasukkan dalam pesan respons API Anda, memperkaya dan menggabungkan data untuk pengguna akhir aplikasi. Anda juga dapat membuat permintaan menggunakan kebijakan ServiceCallout dalam alur permintaan, lalu meneruskan informasi dalam respons ke TargetEndpoint proxy API.
  • Dalam kasus penggunaan lain, Anda memanggil proxy yang berada di organisasi dan lingkungan yang sama dengan proxy yang Anda panggil. Misalnya, Anda mungkin merasa ini berguna saat memiliki proxy yang menawarkan beberapa fungsi tingkat rendah diskrit yang akan digunakan oleh satu atau beberapa proxy lainnya. Misalnya, proxy yang mengekspos operasi buat/baca/perbarui/hapus dengan penyimpanan data backend dapat menjadi proxy target untuk beberapa proxy lain 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 panggilan ke proxy API lokal (yaitu, yang berada di organisasi dan lingkungan yang sama) bernama data-manager, yang menentukan endpoint proxy-nya yang bernama default.

URL sebagai variabel

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

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

Permintaan geocoding / penentuan 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 AssignMessage untuk membuat objek permintaan, Anda dapat menentukannya langsung dalam kebijakan ServiceCallout. Dalam contoh ini, kebijakan ServiceCallout menetapkan nilai 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 kebijakan ServiceCallout.

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

Konten pesan permintaan diekstrak dari variabel yang disebut GeocodingRequest (yang dapat diisi, misalnya, oleh kebijakan AssignMessage). Pesan respons ditetapkan ke variabel yang disebut GeocodingResponse, yang tersedia untuk diuraikan oleh kebijakan ExtractVariables atau oleh kode kustom yang ditulis dalam JavaScript atau Java. Kebijakan menunggu 30 detik untuk mendapatkan respons dari Google Geocoding API sebelum waktunya habis.

Memanggil server target

<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 server tersebut. Dalam contoh ini, beban didistribusikan ke dua server target bernama httpbin dan yahoo. Untuk mengetahui informasi tentang cara menyiapkan Server Target untuk proxy dan mengonfigurasi load balancing, lihat Load balancing di seluruh server backend.

Tentang kebijakan ServiceCallout

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

Panggilan biasanya digunakan dengan dua kebijakan lainnya: AssignMessage dan ExtractVariables.

  • Permintaan: AssignMessage mengisi pesan permintaan yang dikirim ke layanan jarak jauh.

  • Respons: ExtractVariables mengurai respons dan mengekstrak konten tertentu.

Komposisi kebijakan ServiceCallout yang umum meliputi:

  1. Kebijakan AssignMessage: Membuat pesan permintaan, mengisi header HTTP, parameter kueri, menetapkan kata kerja HTTP, dll.

  2. Kebijakan ServiceCallout: Merujuk ke pesan yang dibuat oleh kebijakan AssignMessage, menentukan URL target untuk panggilan eksternal, dan menentukan nama untuk objek respons yang ditampilkan oleh layanan target.

    Untuk meningkatkan performa, Anda juga dapat menyimpan respons ServiceCallout dalam cache, seperti yang dijelaskan dalam Bagaimana cara menyimpan hasil kebijakan ServiceCallout dalam cache? dan kemudian, mengambilnya dari cache?

  3. Kebijakan ExtractVariables: Biasanya menentukan ekspresi JSONPath atau XPath yang mengurai pesan yang dihasilkan oleh ServiceCallout. Kemudian, kebijakan menetapkan variabel yang berisi nilai yang diuraikan dari respons ServiceCallout.

Penanganan error kustom

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi pada 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>

Atribut <ServiceCallout>

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

Tabel berikut menjelaskan atribut yang umum 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.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

 T/A Wajib
continueOnError

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:

 false Opsional
enabled

Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.

 benar Opsional
async

Atribut ini tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami 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

Elemen <Request>

Menentukan variabel yang berisi pesan permintaan yang dikirim dari proxy API ke layanan lain. Variabel dapat dibuat oleh kebijakan sebelumnya dalam alur, atau Anda dapat membuatnya secara 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 kebijakan AssignMessage.

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

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

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

Atau, Anda dapat mengisi pesan permintaan yang dikirim ke layanan eksternal dalam kebijakan ServiceCallout 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 menghilangkan elemen Permintaan, atau salah satu atributnya, Apigee akan menetapkan nilai default berikut:

<Request clearPayload="true" variable="servicecallout.request"/>

Mari kita lihat arti nilai default ini. Pertama, clearPayload=true berarti objek permintaan baru dibuat setiap kali kebijakan ServiceCallout dijalankan. Artinya, permintaan dan jalur URI permintaan tidak pernah digunakan kembali. Kedua, nama variabel default, servicecallout.request, adalah nama yang dicadangkan dan ditetapkan ke permintaan jika Anda tidak memberikan nama.

Anda harus mengetahui nama default ini jika menggunakan penyamaran data -- jika Anda tidak menyertakan nama variabel, Anda harus menambahkan servicecallout.request ke konfigurasi penyamaran. Misalnya, jika Anda ingin memaskan header Otorisasi agar tidak muncul di sesi Debug, Anda akan menambahkan kode berikut ke konfigurasi masking untuk mengambil nama default:

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

Atribut

Atribut Deskripsi Default Kehadiran
variable

Nama variabel yang akan berisi pesan permintaan.

 servicecallout.request Opsional
clearPayload

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

Tetapkan opsi clearPayload ke false hanya jika pesan permintaan diperlukan setelah ServiceCallout dieksekusi.

 true Opsional

Elemen <Request>/<IgnoreUnresolvedVariables>

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

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

Elemen <Response>

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

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

Jika elemen ini tidak ada, proxy API tidak menunggu respons; eksekusi alur Proxy API berlanjut dengan langkah-langkah alur berikutnya. Selain itu, tanpa elemen Response, respons dari target tidak tersedia untuk diproses oleh langkah-langkah berikutnya, 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

Elemen <Timeout>

Waktu dalam milidetik yang akan digunakan kebijakan ServiceCallout untuk menunggu respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika ServiceCallout mengalami waktu tunggu habis, HTTP 500 akan ditampilkan, kebijakan gagal, dan proxy API akan memasuki status error, seperti 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

Elemen <HTTPTargetConnection>

Menyediakan detail transportasi seperti URL, TLS/SSL, dan properti HTTP. Lihat referensi konfigurasi <TargetEndpoint>.

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

Elemen <HTTPTargetConnection>/<Authentication>

Membuat token Google OAuth 2.0 atau OpenID Connect yang dikeluarkan Google untuk melakukan panggilan yang diautentikasi ke layanan Google dan layanan kustom yang berjalan di 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 akan membuat token autentikasi untuk Anda dan menambahkannya ke permintaan layanan.

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

Kebijakan ServiceCallout hanya mendukung panggilan layanan berbasis HTTP.

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

Elemen Authentication menggunakan sintaksis berikut:

Sintaksis

<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, jika ada konfigurasi Autentikasi, Apigee akan membuat token pembawa dan menyisipkannya ke header Authorization dalam pesan yang dikirim ke sistem target. Elemen HeaderName memungkinkan Anda menentukan nama header lain untuk menyimpan token pembawa 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:

Sintaksis

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

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>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</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>
  <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 yang diautentikasi ke layanan Google. Token OAuth Google 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:

Sintaksis

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

<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 melakukan panggilan ke Cloud Run 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>

Mencakup elemen turunan

Mengidentifikasi cakupan yang akan disertakan dalam token akses OAuth 2.0. Untuk mengetahui 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 mengetahui 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

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

Sintaksis

<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 dibuat, seperti API atau akun yang diberi akses oleh token.

Jika nilai Audience kosong atau variabel ref tidak berubah menjadi nilai yang valid, dan useTargetUrl adalah true, maka URL target (tidak termasuk parameter kueri) digunakan sebagai audiens. 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.

Elemen <HTTPTargetConnection>/<URL>

URL ke layanan yang dipanggil:

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

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

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

Atau, tetapkan sebagian 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, serta variabel kedua untuk bagian URL lainnya:

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

Elemen <HTTPTargetConnection>/<SSLInfo>

Konfigurasi TLS/SSL ke layanan backend. Untuk mendapatkan bantuan terkait konfigurasi TLS/SSL, lihat Opsi untuk mengonfigurasi TLS dan "Konfigurasi TargetEndpoint TLS/SSL" 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

Elemen <HTTPTargetConnection>/<Properties>

Properti transportasi HTTP ke layanan backend. Untuk mengetahui 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

Elemen <HTTPTargetConnection>/<LoadBalancer>

Panggil satu atau beberapa server target dan lakukan load balancing di server tersebut. Lihat contoh Panggil server target di bagian Contoh. Lihat juga Load balancing di seluruh server backend. Lihat juga Panggilan endpoint/server target yang membahas cara memanggil server target dari kebijakan ServiceCallout 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

Elemen <LocalTargetConnection>

Menentukan proxy lokal -- yaitu, proxy dalam organisasi dan lingkungan yang sama -- sebagai target panggilan 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

Elemen <LocalTargetConnection>/<APIProxy>

Nama proxy API yang menjadi target panggilan lokal. Proxy harus berada di organisasi dan lingkungan yang sama dengan proxy yang melakukan panggilan.

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

Selain elemen <APIProxy>, sertakan elemen <ProxyEndpoint> untuk menentukan nama endpoint proxy yang harus ditargetkan untuk panggilan.

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

Elemen <LocalTargetConnection>/<ProxyEndpoint>

Nama endpoint proxy yang harus menjadi target panggilan. Ini adalah endpoint proxy di proxy API yang ditentukan dengan elemen <APIProxy>.

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

Elemen <LocalTargetConnection>/<Path>

Jalur ke endpoint yang menjadi target. Endpoint harus merujuk ke proxy dalam organisasi dan lingkungan yang sama dengan proxy yang melakukan panggilan.

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

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

Skema

Variabel alur

Variabel alur memungkinkan perilaku dinamis kebijakan dan Alur saat runtime, berdasarkan header HTTP, konten pesan, atau konteks Alur. Variabel Flow bawaan berikut tersedia setelah kebijakan ServiceCallout dijalankan. Untuk mengetahui informasi selengkapnya tentang variabel Flow, lihat Referensi variabel Flow.

ServiceCallout memiliki permintaan dan responsnya sendiri, dan Anda dapat mengakses data tersebut melalui variabel. Karena pesan utama menggunakan awalan variabel request.* dan response.*, gunakan awalan myrequest.* dan calloutResponse.* (default dalam konfigurasi ServiceCallout) untuk mendapatkan data pesan khusus untuk ServiceCallout. Contoh pertama dalam tabel berikut menunjukkan cara mendapatkan header HTTP di ServiceCallout.

Variabel Deskripsi

Berikut adalah contoh cara mendapatkan header permintaan dan respons ServiceCallout yang serupa dengan cara Anda mendapatkan header dari permintaan dan respons utama.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

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

calloutResponse.header.Content-Length

menampilkan header Content-Length respons ServiceCallout.

Cakupan: Dari ServiceCallout ke depan
Jenis: String
Izin: Baca/Tulis

Header pesan dalam permintaan atau respons ServiceCallout. Misalnya, jika target proxy API adalah http://example.com, dan target ServiceCallout adalah http://mocktarget.apigee.net, variabel ini adalah header untuk callout ke http://mocktarget.apigee.net.
servicecallout.requesturi

Cakupan: Dari permintaan ServiceCallout ke depan
Jenis: String
Izin: Baca/Tulis

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

Cakupan: Dari permintaan ServiceCallout ke depan
Jenis: String
Izin: Baca/Tulis

URL target untuk ServiceCallout.

calloutResponse.content

dengan calloutResponse adalah nama variabel <Response> dalam konfigurasi ServiceCallout.

Cakupan: Dari respons ServiceCallout ke depan
Jenis: String
Izin: Baca/Tulis

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

Cakupan: Dari permintaan ServiceCallout ke depan
Jenis: String
Izin: Baca/Tulis

Nama Umum TargetEndpoint yang diharapkan sebagaimana dirujuk dalam kebijakan ServiceCallout. Nilai ini hanya bermakna jika TargetEndpoint merujuk ke endpoint TLS/SSL.
servicecallout.{policy-name}.failed

Cakupan: Dari respons ServiceCallout ke depan
Jenis: Boolean
Izin: Baca/Tulis

Boolean yang menunjukkan apakah kebijakan berhasil, false, atau gagal, 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