Kebijakan ServiceInfo

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

Apa

Kebijakan Info Layanan memungkinkan Anda melakukan panggilan ke layanan lain dari alur proxy API Anda. Anda dapat membuat pemanggilan 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 info ke API pihak ketiga yang berada di luar proxy Anda. Respons dari API pihak ketiga diuraikan dan dimasukkan ke dalam pesan respons API Anda, yang akan memperkaya dan "menyatukan" data untuk pengguna akhir aplikasi. Anda juga dapat membuat permintaan menggunakan kebijakan Info Layanan dalam alur permintaan, lalu meneruskan informasi tersebut dalam respons ke TargetEndpoint proxy API.
• Dalam kasus penggunaan lain, Anda memanggil proxy yang berada di organisasi dan lingkungan yang sama dengan tempat Anda menelepon. Misalnya, ini mungkin akan berguna saat Anda 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 dapat berupa 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 Info Layanan

Ada banyak skenario yang memungkinkan Anda menggunakan kebijakan Info 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.

Info biasanya digunakan dengan dua kebijakan lainnya: Menetapkan Variabel Pesan dan Ekstrak.

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

• Respons: Ekstrak Variabel akan menguraikan respons dan mengekstrak konten tertentu.

Komposisi kebijakan Info Layanan standar mencakup:

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

Lihat Menggunakan komposisi 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 konfigurasikan 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 <ServiceInfo>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:

Elemen <DisplayName>

Selain atribut name, beri label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa natural yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Elemen <Request>

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

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

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

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 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 menunggu respons; Eksekusi alur Proxy API berlanjut dengan langkah-langkah alur berikutnya. Selain itu, untuk menyatakan dengan jelas, tanpa elemen Response, respons dari target tidak tersedia untuk diproses oleh langkah berikutnya, dan tidak ada cara bagi alur proxy untuk mendeteksi kegagalan dalam panggilan jarak jauh. Penggunaan umum untuk menghilangkan elemen Response saat menggunakan ServiceInfo: untuk mencatat pesan ke sistem eksternal ke dalam log.

 <Response>calloutResponse</Response> 

Elemen <Timeout>

Waktu dalam milidetik saat kebijakan Info Layanan akan menunggu respons dari target. Anda tidak dapat menetapkan nilai ini secara dinamis saat runtime. Jika Info Layanan mengenai waktu tunggu, HTTP 500 akan ditampilkan, kebijakan akan gagal, dan proxy API akan mengalami error, seperti yang dijelaskan dalam Menangani kesalahan.

<Timeout>30000</Timeout>

Elemen <HTTPTargetConnection>

Memberikan detail transpor seperti properti URL, TLS/SSL, dan 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 bagian URL secara dinamis dengan variabel. Namun, bagian protokol dari 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 dari 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 untuk domain dan port saja, 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 Cloud Pribadi) 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 transportasi 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>

Elemen <HTTPTargetConnection>/<LoadBalancer>

Panggil satu atau beberapa server target, lalu lakukan load balancing pada server tersebut. Lihat contoh Server target panggilan 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 di organisasi dan lingkungan yang sama -- sebagai target info layanan.

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

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

Elemen <LocalTargetConnection>/<APIProxy>

Nama proxy API yang merupakan 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 dalam proxy API yang ditentukan dengan elemen <APIProxy>.

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

Elemen <LocalTargetConnection>/<Path>

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

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

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

Skema

Variabel flow

Variabel Flow memungkinkan perilaku kebijakan dan Flow dinamis saat runtime, berdasarkan header HTTP, konten pesan, atau konteks Flow. Variabel Flow yang telah ditetapkan berikut ini tersedia setelah kebijakan Info Layanan dieksekusi. Untuk informasi selengkapnya tentang Variabel alur, lihat Referensi variabel.

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

Error

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

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

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