Kebijakan ServiceCallout

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Apa

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

• Dalam kasus penggunaan eksternal, Anda membuat panggilan ke API pihak ketiga yang eksternal ke proxy Anda. Respons dari API pihak ketiga diuraikan dan dimasukkan dalam pesan respons API Anda, memperkaya dan "menggabungkan" data untuk pengguna akhir aplikasi. Anda juga dapat membuat permintaan menggunakan kebijakan Panggilan Layanan dalam alur permintaan, lalu meneruskan informasi dalam respons ke TargetEndpoint proxy API.
• Dalam kasus penggunaan lain, Anda memanggil proxy yang berada di organisasi dan lingkungan yang sama dengan proxy yang Anda panggil. Misalnya, Anda mungkin merasa ini berguna saat memiliki proxy yang menawarkan beberapa fungsi tingkat rendah diskrit yang akan digunakan oleh satu atau beberapa proxy lainnya. Misalnya, proxy yang mengekspos operasi buat/baca/perbarui/hapus dengan penyimpanan data backend dapat menjadi proxy target untuk beberapa proxy lain yang mengekspos data ke klien.

Kebijakan ini mendukung permintaan melalui HTTP dan HTTPS.

Contoh

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

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

<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>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

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

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

Tentang kebijakan Service Callout

Ada banyak skenario saat Anda dapat menggunakan kebijakan Panggilan Layanan 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.

Pesan singkat biasanya digunakan dengan dua kebijakan lainnya: Tetapkan Pesan dan Ekstrak Variabel.

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

• Respons: Kebijakan Extract Variables mengurai respons dan mengekstrak konten tertentu.

Komposisi kebijakan Service Callout yang umum meliputi:

1. Kebijakan Tetapkan Pesan: Membuat pesan permintaan, mengisi header HTTP, parameter kueri, menetapkan kata kerja HTTP, dll.
2. Kebijakan Panggilan Layanan: Merujuk ke pesan yang dibuat oleh kebijakan Tetapkan Pesan, menentukan URL target untuk panggilan eksternal, dan menentukan nama untuk objek respons yang ditampilkan oleh layanan target.
   
   Untuk meningkatkan performa, Anda juga dapat menyimpan respons Panggilan Layanan dalam cache, seperti yang dijelaskan dalam rangkaian pesan Komunitas Apigee ini: How can I store the results of the ServiceCallout policy in cache and later retrieve it from cache?.
3. Ekstrak Variabel policy: Biasanya menentukan ekspresi JSONPath atau XPath yang mengurai pesan yang dihasilkan oleh Panggilan Layanan. Kemudian, kebijakan menetapkan variabel yang berisi nilai yang diuraikan dari respons Panggilan Layanan.

Lihat Menggunakan komposisi kebijakan untuk mengetahui contoh lengkap proxy API yang menggunakan kebijakan Panggilan Layanan bersama dengan kebijakan Tetapkan Pesan dan Ekstrak Variabel.

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>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </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:

&lt;DisplayName&gt; elemen

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

<DisplayName>Policy Display Name</DisplayName>

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 Panggilan Layanan.

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

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

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

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

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

Atau, Anda dapat mengisi pesan permintaan yang dikirim ke layanan eksternal dalam kebijakan Service Callout 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>

Atribut

Elemen <Request>/<IgnoreUnresolvedVariables>

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

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

Elemen <Response>

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

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

Jika elemen ini tidak ada, proxy API tidak menunggu respons; eksekusi alur Proxy API berlanjut dengan langkah-langkah alur berikutnya. Selain itu, tanpa elemen Response, respons dari target tidak tersedia untuk diproses oleh langkah-langkah berikutnya, dan tidak ada cara bagi alur proxy untuk mendeteksi kegagalan dalam panggilan jarak jauh. Penggunaan umum untuk menghilangkan elemen Response saat menggunakan ServiceCallout: untuk mencatat pesan ke sistem eksternal.

 <Response>calloutResponse</Response>

Elemen <Timeout>

Waktu dalam milidetik yang akan digunakan kebijakan Service Callout untuk menunggu respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika Panggilan Layanan mengalami waktu tunggu habis, HTTP 500 akan ditampilkan, kebijakan gagal, dan proxy API akan memasuki status error, seperti yang dijelaskan dalam Menangani kesalahan.

<Timeout>30000</Timeout>

Elemen <HTTPTargetConnection>

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

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

Elemen <HTTPTargetConnection>/<URL>

URL ke layanan yang dipanggil:

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

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

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

Atau, tetapkan sebagian jalur URL dengan variabel:

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

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

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

Elemen <HTTPTargetConnection>/<SSLInfo>

Konfigurasi TLS/SSL ke layanan backend. Untuk mendapatkan bantuan terkait konfigurasi TLS/SSL, lihat Mengonfigurasi TLS dari Edge ke backend (Cloud dan Private Cloud) 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>

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

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

Elemen <HTTPTargetConnection>/<LoadBalancer>

Panggil satu atau beberapa server target dan lakukan load balancing di server tersebut. Lihat contoh Panggil server target di bagian Contoh. Lihat juga Load balancing di seluruh server backend. Lihat juga postingan komunitas ini yang membahas cara memanggil server target dari kebijakan Panggilan Layanan dan menggunakan Aturan Rute.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

Elemen <LocalTargetConnection>

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

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

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

Elemen <LocalTargetConnection>/<APIProxy>

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

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

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

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>

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>

Elemen <LocalTargetConnection>/<Path>

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

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

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

Skema

Variabel alur

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

Panggilan Layanan 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 Info Layanan) untuk mendapatkan data pesan khusus untuk Info Layanan. Contoh pertama dalam tabel berikut menunjukkan cara mendapatkan header HTTP di Panggilan Layanan.

Error

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

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Error saat deployment

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

Variabel kesalahan

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

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: Tetapkan kebijakan Pesan
• Ekstrak variabel: Extract Variables policy
• Variabel: Referensi variabel
• Konfigurasi TLS/SSL
  • Mengonfigurasi TLS dari Edge ke backend (Cloud dan Private Cloud)
  • "Konfigurasi TargetEndpoint TLS/SSL" di Referensi konfigurasi proxy API
• Properti transportasi HTTP: Referensi properti endpoint
• Alternatif untuk Panggilan Layanan: HTTPClient yang ditulis dalam JavaScript, lihat Model objek JavaScript