Kebijakan ServiceCallout

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

Apa

Kebijakan Info Layanan 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 dalam organisasi dan lingkungan yang sama).

• Dalam kasus penggunaan eksternal, Anda membuat pemanggilan ke API pihak ketiga yang berada di luar cakupan {i>proxy<i}. Respons dari API pihak ketiga akan diuraikan dan disisipkan dalam respons API Anda pesan, memperkaya dan "menggabungkan" data untuk pengguna akhir aplikasi. Anda juga dapat mengajukan permintaan menggunakan kebijakan Info Layanan dalam alur permintaan, lalu meneruskan informasi dalam respons ke TargetEndpoint proxy API.
• Dalam kasus penggunaan lain, Anda memanggil {i>proxy<i} yang ada di organisasi dan lingkungan yang sama dengan nomor yang Anda gunakan. Misalnya, Anda mungkin menemukan bahwa ini berguna ketika Anda memiliki {i>proxy<i} yang menawarkan beberapa fungsionalitas tingkat rendah yang akan digunakan oleh satu atau lebih {i>proxy<i} lainnya. Sebagai contoh, proxy yang mengekspos operasi buat/baca/perbarui/hapus dengan penyimpanan data backend dapat menjadi {i>proxy<i} target untuk beberapa {i>proxy<i} lainnya 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 Info Layanan

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

Info biasanya digunakan dengan dua kebijakan lain: Tetapkan Pesan dan Ekstrak Variabel.

• Permintaan: Tetapkan Pesan akan mengisi pesan permintaan yang dikirim ke remote layanan.

• Respons: Ekstrak Variabel akan mengurai respons dan mengekstrak variabel saat ini.

Komposisi kebijakan Info Layanan standar mencakup:

1. Tetapkan Pesan kebijakan: Membuat pesan permintaan, mengisi header HTTP, parameter kueri, menetapkan HTTP verba, dll.
2. Kebijakan Info Layanan: Mereferensikan pesan yang dibuat oleh Tetapkan Pesan kebijakan, 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 Info Layanan, seperti yang dijelaskan dalam Rangkaian pesan Komunitas Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Mengekstrak Variabel policy: Biasanya menentukan ekspresi JSONPath atau XPath yang mengurai pesan yang dihasilkan di Info Layanan. Kebijakan ini kemudian menetapkan variabel yang berisi nilai yang diuraikan dari Respons Info Layanan.

Lihat Menggunakan kebijakan untuk contoh proxy API lengkap yang menggunakan kebijakan Panggilan Layanan beserta kebijakan Tetapkan Pesan dan Ekstrak Variabel.

Penanganan error kustom

Referensi elemen

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

&lt;ServiceCallout&gt; atribut

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

&lt;Request&gt; elemen

Menentukan variabel berisi pesan permintaan yang dikirim dari proxy API ke layanan lainnya. Variabel dapat dibuat oleh kebijakan sebelumnya dalam alur, atau Anda dapat membuatnya secara inline pada kebijakan Pemanggilan 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 Tetapkan Pesan kebijakan kami.

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

Dalam contoh yang 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 Info Layanan 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

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; elemen

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

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

&lt;Response&gt; elemen

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

Jika ada, elemen ini menentukan nama variabel yang akan berisi pesan respons yang diterima dari layanan eksternal. Respons dari target ditugaskan kepada variabel hanya ketika 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 menunggu respons; Alur Proxy API dan eksekusi akan dilanjutkan dengan langkah-langkah alur berikutnya. Juga, untuk menyatakan hal yang sudah jelas, tanpa Response, respons dari target tidak tersedia untuk diproses oleh langkah selanjutnya, 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> 

<Waktu tunggu> elemen

Waktu dalam milidetik saat kebijakan Pemanggilan Layanan akan menunggu respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika Pemanggilan Layanan mencapai waktu tunggu, HTTP 500 dikembalikan, kebijakan gagal, dan proxy API masuk ke status kesalahan, seperti yang dijelaskan dalam Menangani kesalahan.

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; elemen

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

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; elemen

URL ke layanan yang dipanggil:

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

Anda dapat menyediakan bagian URL secara dinamis dengan variabel. Namun, bagian protokol dari URL, http:// di bawah, tidak boleh yang ditentukan oleh variabel. Pada contoh berikutnya, Anda menggunakan variabel untuk menentukan nilai 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 lain dari URL:

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

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; elemen

Konfigurasi TLS/SSL ke layanan backend. Untuk bantuan tentang konfigurasi TLS/SSL, lihat Mengonfigurasi TLS dari Edge ke backend (Cloud dan Private Cloud) dan "TLS/SSL TargetEndpoint Configuration" 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 transpor HTTP ke layanan backend. Untuk 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>

&lt;HTTPTargetConnection&gt;/&lt;LoadBalancer&gt; elemen

Panggil satu atau beberapa server target dan lakukan load balancing pada server tersebut. Lihat Target panggilan server di bagian Contoh. Lihat juga Load balancing di seluruh backend server. Lihat juga komunitas ini post yang membahas cara untuk memanggil server target dari kebijakan Service Keterangan dan menggunakan Aturan Rute.

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

&lt;LocalTargetConnection&gt; elemen

Menentukan proxy lokal -- yaitu, proxy dalam organisasi dan lingkungan yang sama -- seperti target info layanan.

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

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

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; elemen

Nama proxy API yang merupakan target panggilan lokal. Proxy harus sama organisasi dan lingkungan sebagai {i> proxy<i} yang melakukan panggilan.

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

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

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

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; elemen

Nama endpoint proxy yang harus menjadi target panggilan. Ini adalah titik akhir {i>proxy<i} di proxy API yang ditetapkan dengan elemen <APIProxy>.

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; elemen

Jalur ke endpoint yang ditarget. Endpoint harus merujuk ke proxy dalam organisasi dan lingkungan sebagai {i> proxy<i} yang melakukan panggilan.

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

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

Skema

Variabel flow

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

Pemanggilan Layanan memiliki permintaan dan respons sendiri, dan Anda dapat mengakses data tersebut melalui variabel. Karena pesan utama menggunakan request.* dan Awalan variabel response.*, gunakan myrequest.* dan Awalan calloutResponse.* (default dalam konfigurasi Info Layanan) ke mendapatkan data pesan khusus untuk Info Layanan. Contoh pertama dalam tabel berikut menunjukkan cara mendapatkan {i>header<i} HTTP di {i>Service callout<i}.

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