Kebijakan ServiceCallout

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

ikon kebijakan

Apa

Kebijakan ServiceCallout memungkinkan Anda melakukan panggilan ke layanan lain dari alur proxy API. Anda dapat membuat info ke layanan eksternal (seperti endpoint layanan RESTful eksternal) atau layanan internal (seperti proxy API di 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 informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.

  • Dalam kasus penggunaan eksternal, Anda membuat panggilan ke API pihak ketiga yang bersifat eksternal terhadap proxy Anda. Respons dari API pihak ketiga diuraikan dan disisipkan dalam pesan respons API Anda, yang 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 tempat Anda melakukan panggilan. Misalnya, Anda mungkin merasa ini berguna jika memiliki proxy yang menawarkan beberapa fungsi tingkat rendah terpisah yang akan digunakan oleh satu atau beberapa proxy lainnya. Misalnya, proxy yang mengekspos operasi create/read/update/delete 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 info ke proxy API lokal (yaitu, satu di organisasi dan lingkungan yang sama) yang disebut data-manager, yang menentukan endpoint proxy-nya yang namanya adalah 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 / definisi 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 ini menunggu 30 detik untuk respons dari Google Geocoding API sebelum waktu 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 di dua server target bernama httpbin dan yahoo. Untuk 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 tempat 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.

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

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

  • Response: ExtractVariables mengurai respons dan mengekstrak konten tertentu.

Komposisi kebijakan ServiceCallout yang umum melibatkan:

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

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

    Untuk meningkatkan performa, Anda juga dapat meng-cache respons ServiceCallout, 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. Kebijakan kemudian 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 di-resolve atau merupakan jenis pesan permintaan yang 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 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 yang ditetapkan ke permintaan jika Anda tidak memberikan nama.

Penting untuk mengetahui nama default ini jika Anda menggunakan masking data -- jika Anda menghilangkan nama variabel, Anda harus menambahkan servicecallout.request ke konfigurasi mask. Misalnya, jika ingin menyamarkan header Authorization agar tidak muncul dalam sesi Debug, Anda harus 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 salah hanya jika pesan permintaan diperlukan setelah ServiceCallout dieksekusi.

 benar Opsional

Elemen <Request>/<IgnoreUnresolvedVariables>

Jika disetel ke true, kebijakan ini 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 akan 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 dihilangkan, proxy API tidak akan menunggu respons; eksekusi alur Proxy API akan dilanjutkan dengan langkah alur berikutnya. Selain itu, untuk menyatakan hal yang jelas, 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 ditunggu kebijakan ServiceCallout untuk mendapatkan respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika ServiceCallout mengalami waktu tunggu habis, HTTP 500 akan ditampilkan, kebijakan akan gagal, dan proxy API akan berstatus error, seperti yang dijelaskan dalam Menangani error.

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

Elemen <HTTPTargetConnection>

Memberikan detail transpor 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>

Menghasilkan token Google OAuth 2.0 atau OpenID Connect yang diterbitkan 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:

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

<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

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

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 pengelola secret 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 membuat 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>

Elemen turunan cakupan

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

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:

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 diberi akses oleh token.

Jika nilai Audience kosong atau variabel ref tidak me-resolve ke nilai yang valid, dan useTargetUrl adalah true, URL target (tidak termasuk parameter kueri) akan 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 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.

Elemen <HTTPTargetConnection>/<URL>

URL ke layanan yang dipanggil:

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

Anda dapat menyediakan bagian URL secara dinamis dengan variabel. Namun, bagian protokol URL, http:// di bawah, tidak dapat ditentukan oleh variabel. Pada contoh berikutnya, Anda menggunakan variabel untuk menentukan nilai parameter 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 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 transpor 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 pada server tersebut. Lihat contoh Server target panggilan di Bagian contoh. Lihat juga Load balancing di seluruh server backend. Lihat juga Penjelasan 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 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

Elemen <LocalTargetConnection>/<APIProxy>

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

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

Bersama dengan 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 ditargetkan. 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 tersebut mungkin merupakan target yang andal.

<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 standar berikut tersedia setelah kebijakan ServiceCallout dieksekusi. Untuk informasi selengkapnya tentang variabel Flow, lihat Referensi variabel Flow.

ServiceCallouts 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 mirip dengan cara Anda mendapatkan header dari permintaan dan respons utama.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

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

calloutResponse.header.Content-Length

menampilkan header Content-Length dari respons ServiceCallout.

Cakupan: Dari ServiceCallout dan seterusnya
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 seperti yang disebutkan dalam kebijakan ServiceCallout. Hal ini hanya berlaku 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, salah, atau gagal, benar.

Error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kerusakan Status HTTP Penyebab Perbaiki
steps.servicecallout.ExecutionFailed 500

Error ini dapat terjadi jika:

  • Kebijakan diminta untuk menangani input yang salah format atau tidak valid.
  • Layanan target backend menampilkan status error (secara default, 4xx atau 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 Variabel Request yang ditentukan dalam kebijakan bukan dari jenis Message. Misalnya, jika berupa string atau jenis non-pesan lainnya, Anda akan melihat error ini.
steps.servicecallout.RequestVariableNotRequestMessageType 500 Variabel Request yang ditentukan dalam kebijakan bukan dari jenis RequestMessage. Misalnya, jika jenisnya adalah Response, Anda akan melihat error ini.
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.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Error ini dapat terjadi jika proxy API dikonfigurasi dengan elemen <Authentication>. Kemungkinan penyebabnya meliputi:
  • Akun layanan yang di-deploy dengan proxy:
    • tidak ada dalam project Anda
    • telah dinonaktifkan
    • (Khusus Apigee hybrid) belum memberikan peran roles/iam.serviceAccountTokenCreator di akun layanan apigee-runtime.
  • IAMCredentials API dinonaktifkan di project sumber akun layanan apigee-runtime.
  • Elemen <GoogleAccessToken> digunakan dan satu atau beberapa cakupan yang tidak valid diberikan. Misalnya, cari kesalahan ketik atau cakupan kosong.

    • Khusus untuk Apigee hybrid, periksa log penampung runtime dan telusuri GoogleTokenGenerationFailure untuk menemukan pesan error yang lebih mendetail yang dapat membantu proses debug masalah.

    Error saat deployment

    Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

    Nama error Penyebab Perbaiki
    URLMissing Elemen <URL> di dalam <HTTPTargetConnection> tidak ada atau kosong.
    ConnectionInfoMissing Error ini terjadi jika kebijakan tidak memiliki elemen <HTTPTargetConnection> atau <LocalTargetConnection>.
    InvalidTimeoutValue Error ini terjadi jika nilai <Timeout> negatif atau nol.
    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.

    Variabel error

    Variabel ini ditetapkan saat error runtime terjadi. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang 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 error adalah bagian terakhir dari kode error. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. servicecallout.SC-GetUserData.failed = true

    Contoh respons error

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

    Contoh aturan error

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

    Topik terkait