Kebijakan InfoLayanan

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

ikon kebijakan

Apa

Kebijakan ServiceCallout 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 di organisasi dan lingkungan yang sama).

Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, 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 proxy Anda. Respons dari API pihak ketiga diuraikan dan disisipkan dalam pesan respons API Anda, sehingga memperkaya dan menggabungkan data untuk pengguna akhir aplikasi. Anda juga dapat membuat permintaan menggunakan kebijakan ServiceCallout dalam alur permintaan, lalu meneruskan informasi dalam respons tersebut ke TargetEndpoint proxy API.
  • Dalam kasus penggunaan lain, Anda memanggil proxy yang berada dalam organisasi dan lingkungan yang sama dengan tempat asal panggilan Anda. Misalnya, Anda mungkin merasa hal ini berguna saat memiliki proxy yang menawarkan beberapa fungsi tingkat rendah terpisah yang akan digunakan oleh satu atau beberapa proxy lain. Misalnya, proxy yang mengekspos operasi buat/baca/perbarui/hapus dengan penyimpanan data backend bisa 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 dalam URL untuk mengisi URL target secara dinamis. Bagian protokol dari URL, http://, tidak dapat ditentukan oleh variabel. Selain itu, Anda harus menggunakan variabel terpisah untuk bagian domain URL dan untuk seluruh URL.

Geocoding / definisikan 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 kebijakanAssignMessage untuk membuat objek permintaan, Anda dapat menentukannya secara langsung di kebijakan ServiceCallout. Dalam contoh ini, kebijakan ServiceCallout menetapkan nilai dari tiga parameter kueri yang diteruskan ke layanan eksternal. Anda dapat membuat seluruh pesan permintaan dalam kebijakan ServiceCallout yang menentukan payload dan jenis encoding seperti application/xml, header, parameter formulir, dsb.

Berikut 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 produksi yang ditetapkan). Pesan respons ditetapkan ke variabel bernama GeocodingResponse, yang dapat diurai 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.

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 server tersebut. Dalam contoh ini, beban didistribusikan ke dua server target yang 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 InfoLayanan

Ada banyak skenario saat Anda dapat menggunakan kebijakan ServiceCallout di proxy API Anda. 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: ApplyMessage mengisi pesan permintaan yang dikirim ke layanan jarak jauh.

  • Response: ExtractVariables mengurai respons dan mengekstrak konten tertentu.

Komposisi kebijakan ServiceCallout umumnya meliputi:

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

  2. Kebijakan ServiceCallout: Mereferensikan 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 meng-cache respons ServiceCallout, seperti yang dijelaskan dalam Bagaimana cara menyimpan hasil kebijakan ServiceCallout di cache? dan nanti, mengambilnya dari cache?

  3. Kebijakan ExtractVariables: Biasanya menentukan ekspresi JSONPath atau XPath yang mengurai pesan yang dihasilkan oleh ServiceCallout. Kebijakan ini 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 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

Elemen <Request>

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

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

Dalam contoh 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 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 menetapkan nilai default berikut:

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

Mari kita lihat apa arti nilai-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 untuk permintaan jika Anda tidak memberikan nama.

Penting untuk mengetahui nama default ini jika Anda menggunakan data masking. Jika menghapus nama variabel, Anda harus menambahkan servicecallout.request ke konfigurasi mask. Misalnya, jika Anda ingin menyamarkan header Otorisasi agar tidak muncul di sesi Debug, Anda perlu menambahkan kode berikut ke konfigurasi masking untuk mengambil nama default:

servicecallout.request.header.Authorization.
Kehadiran Opsional.
Type 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 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 dijalankan.

 true Opsional

Elemen <Request>/<IgnoreUnresolvedVariables>

Jika ditetapkan 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
Type Boolean

Elemen <Response>

Sertakan elemen ini ketika logika proxy API memerlukan respons dari panggilan jarak jauh untuk diproses 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 berlanjut dengan langkah alur berikutnya. Selain itu, sebagai pernyataan yang sudah jelas, tanpa elemen Response, respons dari target tidak tersedia untuk diproses dengan langkah-langkah berikutnya, dan alur proxy tidak dapat 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
Type String

Elemen <Timeout>

Waktu dalam milidetik saat kebijakan ServiceCallout akan menunggu respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika ServiceCallout mencapai waktu tunggu, HTTP 500 akan ditampilkan, kebijakan akan gagal, dan proxy API akan mengalami 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
Type Bilangan bulat

Elemen <HTTPTargetConnection>

Memberikan detail transportasi 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 Diperlukan
Type T/A

Elemen <HTTPTargetConnection>/<Authentication>

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

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

Kebijakan ServiceCallout hanya mendukung panggilan layanan berbasis HTTP.

Default T/A
Wajib? Opsional.
Type 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 menampilkan elemen GoogleAccessToken:

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

Menggunakan GoogleIDToken

Contoh berikut menampilkan elemen GoogleIDToken:

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

Menggunakan HeaderName

Contoh berikut menampilkan 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 menampilkan 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, ketika ada konfigurasi Authentication, Apigee akan menghasilkan token pemilik dan memasukkannya ke header Authorization dalam pesan yang dikirim ke sistem target. Elemen HeaderName memungkinkan Anda menentukan nama header yang berbeda untuk menyimpan token pembawa tersebut. Fitur ini sangat berguna jika targetnya adalah layanan Cloud Run yang menggunakan header X-Serverless-Authorization. Header Authorization, jika ada, tidak diubah dan juga dikirim dalam permintaan.

Default T/A
Wajib? Tidak
Type 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 sebagai ganti 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 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.
Type 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 menampilkan elemen GoogleAccessToken:

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

Contoh 2

Contoh berikut menunjukkan cara menghubungkan 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 membuat info ke Cloud 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>

Mencakup 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? Diperlukan
Type 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.
Type String
Elemen Induk <Scopes>
Elemen Turunan Tidak ada.

Elemen turunan LifetimeInSeconds

Menentukan durasi masa aktif token akses dalam detik.

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

Elemen turunan GoogleIDToken

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

Default T/A
Wajib? Elemen turunan GoogleAccessToken atau GoogleIDToken harus ada.
Type 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 menampilkan 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 dapat diakses oleh token tersebut.

Jika nilai Audience kosong atau variabel ref tidak di-resolve menjadi nilai yang valid, dan useTargetUrl adalah true, URL target (tidak termasuk parameter kueri apa pun) akan 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? Diperlukan
Type 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
Type Boolean
Elemen Induk <GoogleIDToken>
Elemen Turunan Tidak ada.

Elemen <HTTPTargetConnection>/<URL>

URL ke layanan yang sedang 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. 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, serta variabel kedua untuk bagian URL lainnya:

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

Elemen <HTTPTargetConnection>/<SSLInfo>

Konfigurasi TLS/SSL ke layanan backend. Untuk bantuan tentang 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
Type 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
Type T/A

Elemen <HTTPTargetConnection>/<LoadBalancer>

Panggil satu atau beberapa server target dan lakukan load balancing pada server tersebut. Lihat contoh Call target server di bagian Sample. Lihat juga Load balancing di seluruh server backend. Lihat juga Target Endpoint/Server callout 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
Type T/A

Elemen <LocalTargetConnection>

Menentukan proxy lokal -- yaitu, proxy dalam organisasi dan lingkungan yang sama -- sebagai target pemanggilan layanan.

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

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
Default T/A
Kehadiran Diperlukan
Type 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 Diperlukan
Type String

Elemen <LocalTargetConnection>/<ProxyEndpoint>

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

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

Elemen <LocalTargetConnection>/<Path>

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

Gunakan ini sebagai ganti pasangan <APIProxy>/<ProxyEndpoint> jika Anda tidak tahu -- atau tidak dapat mengandalkan -- nama proxy. Jalur itu mungkin target yang dapat diandalkan.

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

Skema

Variabel alur

Variabel flow memungkinkan perilaku dinamis kebijakan dan Flow saat runtime, berdasarkan header HTTP, konten pesan, atau konteks Flow. Variabel Alur standar berikut tersedia setelah kebijakan ServiceCallout dijalankan. 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 Request. Contoh:

calloutResponse.header.Content-Length

menampilkan header Content-Length respons ServiceCallout.

Cakupan: Dari penerusan ServiceCallout
Type: String
Permission: Baca/Tulis

Header pesan di 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 pemanggilan ke http://mocktarget.apigee.net.
servicecallout.requesturi

Cakupan: Dari selanjutnya permintaan ServiceCallout
Type: String
Permission: Baca/Tulis

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

Cakupan: Dari selanjutnya permintaan ServiceCallout
Type: String
Permission: Baca/Tulis

URL target untuk ServiceCallout.

calloutResponse.content

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

Cakupan: Dari penerusan respons ServiceCallout berikutnya
Type: String
Permission: Read/Write

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

Cakupan: Dari selanjutnya permintaan ServiceCallout
Type: String
Permission: Baca/Tulis

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

Cakupan: Dari respons ServiceCallout selanjutnya
Type: Boolean
Izin: Baca/Tulis

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

Error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab Perbaikan
steps.servicecallout.ExecutionFailed 500

Error ini dapat terjadi jika:

  • Kebijakan akan 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 jenis Message. Misalnya, jika ini adalah string atau jenis non-pesan lainnya, Anda akan melihat error ini.
steps.servicecallout.RequestVariableNotRequestMessageType 500 Variabel Request yang ditentukan dalam kebijakan bukan jenis RequestMessage. Misalnya, jika ini adalah jenis Respons, Anda akan melihat error ini.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> diaktifkan, tetapi useTargetUrl ditetapkan ke salah (false) dan tidak ada nilai yang diberikan ke <Audience> baik secara langsung maupun melalui referensi pada saat terjadi 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 di project Anda
    • telah dinonaktifkan
    • (Khusus Apigee Hybrid) belum memberikan peran roles/iam.serviceAccountTokenCreator pada akun layanan apigee-runtime.
  • IAMCredentials API dinonaktifkan dalam project sumber akun layanan apigee-runtime.
  • Elemen <GoogleAccessToken> digunakan dan satu atau beberapa cakupan tidak valid disediakan. Misalnya, cari kesalahan ketik atau cakupan kosong.

    • Khusus Apigee Hybrid, periksa log container runtime dan telusuri GoogleTokenGenerationFailure untuk menemukan pesan error lebih detail 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 Perbaikan
    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 dikonfigurasikan 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 pada 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 kesalahan

    Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

    Variabel Dari mana Contoh
    fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. 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 kesalahan

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

    Topik terkait