Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
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:
- AssignMessage: Membuat pesan permintaan, mengisi header HTTP, parameter kueri, menetapkan kata kerja HTTP, dll.
-
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?
- 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 Atau, gunakan elemen |
T/A | Diperlukan |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
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 |
---|---|
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,
Penting untuk mengetahui nama default ini jika Anda menggunakan data masking. Jika menghapus nama variabel, Anda harus menambahkan |
Kehadiran | Opsional. |
Type | T/A |
Atribut
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
variabel |
Nama variabel yang akan berisi pesan permintaan. |
servicecallout.request |
Opsional |
clearPayload |
Jika 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.
dengan calloutResponse adalah nama variabel untuk Respons di Info Layanan, dan myRequest adalah nama variabel untuk Request. Contoh:
menampilkan header Content-Length respons ServiceCallout. |
Cakupan: Dari penerusan ServiceCallout 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 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 URL target untuk ServiceCallout. |
dengan |
Cakupan: Dari penerusan respons ServiceCallout berikutnya Isi respons dari ServiceCallout. |
servicecallout.{policy-name}.expectedcn |
Cakupan: Dari selanjutnya permintaan ServiceCallout 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 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:
|
build |
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. |
build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 |
Variabel Request yang ditentukan dalam kebijakan bukan jenis RequestMessage . Misalnya, jika ini adalah jenis Respons, Anda akan melihat error ini. |
build |
googletoken.EmptyIDTokenAudience |
500 |
|
|
messaging.adaptors.http.filter.GoogleTokenGenerationFailure |
500 |
Error ini dapat terjadi jika proxy API dikonfigurasi dengan elemen <Authentication>. Kemungkinan penyebabnya meliputi:
<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
|
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. |
build |
ConnectionInfoMissing |
Error ini terjadi jika kebijakan tidak memiliki elemen
<HTTPTargetConnection> atau
<LocalTargetConnection> . |
build |
InvalidTimeoutValue |
Error ini terjadi jika nilai <Timeout> negatif atau nol. |
build |
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:
|
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
- Membuat atau mengubah pesan: AssignMessage
- Mengekstrak variabel: Kebijakan ExtractVariables
- Variabel: Referensi variabel flow
- Konfigurasi TLS/SSL
- Opsi untuk mengonfigurasi TLS
- "Konfigurasi TargetEndpoint TLS/SSL" dalam referensi konfigurasi proxy API
- Properti transpor HTTP: Referensi properti endpoint
- Alternatif untuk ServiceCallout: HTTPClient yang ditulis dalam JavaScript, lihat model objek JavaScript.