Chính sách Chú thích dịch vụ

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến Tài liệu về Apigee X. thông tin

Nội dung

Chính sách Chú thích dịch vụ cho phép bạn gọi đến một dịch vụ khác trong luồng proxy API của mình. Bạn có thể tạo chú thích cho một dịch vụ bên ngoài (chẳng hạn như điểm cuối của dịch vụ Kiến trúc chuyển trạng thái đại diện (REST) bên ngoài) hoặc dịch vụ nội bộ (chẳng hạn như proxy API trong cùng một tổ chức và môi trường).

• Trong trường hợp sử dụng bên ngoài, bạn tạo chú thích cho API của bên thứ ba ngoài API của bên thứ ba proxy. Phản hồi của API bên thứ ba được phân tích cú pháp và chèn vào phản hồi của API thông điệp, làm phong phú và "kết hợp" dữ liệu cho người dùng cuối ứng dụng. Bạn cũng có thể gửi yêu cầu sử dụng chính sách Chú thích dịch vụ trong quy trình yêu cầu, sau đó chuyển thông tin vào phản hồi đến TargetEndpoint của proxy API.
• Trong một trường hợp sử dụng khác, bạn gọi một proxy trong cùng tổ chức và môi trường với mà bạn đang dùng để gọi điện. Ví dụ: bạn có thể thấy tính năng này hữu ích khi có một proxy cung cấp một số chức năng riêng biệt cấp thấp mà một hoặc nhiều proxy khác sẽ sử dụng. Cho ví dụ: một proxy hiển thị các thao tác tạo/đọc/cập nhật/xoá với một kho dữ liệu phụ trợ có thể là proxy mục tiêu cho nhiều proxy khác hiển thị dữ liệu cho ứng dụng khách.

Chính sách này hỗ trợ các yêu cầu qua HTTP và HTTPS.

Mẫu

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

Giới thiệu về chính sách Chú thích dịch vụ

Có nhiều trường hợp mà bạn có thể sử dụng chính sách Chú thích dịch vụ trong proxy API. Cho ví dụ: bạn có thể định cấu hình proxy API để thực hiện lệnh gọi đến một dịch vụ bên ngoài cần phân phối dữ liệu định vị vị trí, bài đánh giá của khách hàng, các mặt hàng trong danh mục bán lẻ của đối tác, v.v.

Chú thích thường được sử dụng cùng với hai chính sách khác: Chỉ định thông báo và trích xuất biến.

• Yêu cầu: Chỉ định tin nhắn sẽ điền thông báo yêu cầu được gửi đến điều khiển từ xa .

• Phản hồi: Trích xuất biến sẽ phân tích cú pháp phản hồi và trích xuất dữ liệu cụ thể nội dung.

Cấu trúc chính sách Chú thích dịch vụ điển hình bao gồm:

1. Gửi tin nhắn chính sách: Tạo thông báo yêu cầu, điền tiêu đề HTTP, tham số truy vấn, đặt HTTP động từ, v.v.
2. Chính sách về Chú thích dịch vụ: Đề cập đến một thông báo do tuỳ chọn Chỉ định thông báo tạo chính sách, xác định URL mục tiêu cho lệnh gọi bên ngoài và xác định tên cho đối tượng phản hồi mà dịch vụ mục tiêu trả về.
   
   Để cải thiện hiệu suất, bạn cũng có thể lưu các phản hồi của Chú thích dịch vụ vào bộ nhớ đệm, như mô tả trong Chuỗi bài đăng trên cộng đồng Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Trích xuất biến policy: Thường xác định biểu thức JSONPath hoặc NETWORK phân tích cú pháp thông báo được tạo theo Chú thích dịch vụ. Sau đó, chính sách này đặt các biến chứa giá trị được phân tích cú pháp từ Phản hồi về chú thích dịch vụ.

Xem Chính sách sử dụng cấu trúc để có proxy API mẫu hoàn chỉnh sử dụng Chính sách Chú thích dịch vụ cùng với chính sách Gán thông báo và trích xuất biến.

Xử lý lỗi tuỳ chỉnh

Tham chiếu phần tử

Sau đây là các phần tử và thuộc tính mà bạn có thể thiết lập theo chính sách này:

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

<ServiceCallout> thuộc tính

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

Bảng sau đây mô tả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

<DisplayName> phần tử

Hãy sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong phần trình chỉnh sửa proxy giao diện người dùng quản lý có tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>

<Request> phần tử

Chỉ định biến chứa thông báo yêu cầu được gửi từ proxy API đến dịch vụ khác. Bạn có thể tạo biến bằng một chính sách trước đó trong quy trình hoặc bạn có thể tạo biến đó cùng dòng trong chính sách Chú thích dịch vụ.

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

Cú pháp cho các thẻ <Remove>, <Copy>, <Add> và <Set> tương tự như cú pháp cho thẻ Gửi tin nhắn .

Chính sách này sẽ trả về lỗi nếu thông báo yêu cầu không giải quyết được hoặc là thông báo không hợp lệ loại thông báo yêu cầu.

Trong ví dụ đơn giản nhất, bạn truyền một biến có chứa thông báo yêu cầu được điền sẵn trước đó trong quy trình của proxy API:

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

Hoặc bạn có thể điền thông báo yêu cầu gửi đến dịch vụ bên ngoài ngay trong chính sách Chú thích dịch vụ:

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

Thuộc tính

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; phần tử

Khi bạn đặt chính sách này thành true, chính sách sẽ bỏ qua mọi lỗi biến chưa được giải quyết trong yêu cầu.

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

&lt;Response&gt; phần tử

Thêm phần tử này khi logic proxy API yêu cầu phản hồi từ lệnh gọi từ xa cho tiếp tục xử lý.

Khi có phần tử này, phần tử này sẽ chỉ định tên của biến chứa tin nhắn phản hồi nhận được từ dịch vụ bên ngoài. Phản hồi từ mục tiêu được chỉ định cho biến chỉ khi chính sách đọc thành công toàn bộ phản hồi. Nếu cuộc gọi từ xa không thành công vì bất kỳ lý do gì thì chính sách sẽ trả về lỗi.

Nếu phần tử này bị bỏ qua, proxy API sẽ không chờ phản hồi; Luồng proxy API tiếp tục thực thi với bất kỳ bước luồng tiếp theo nào. Ngoài ra, để nêu rõ rằng việc không Response, phản hồi từ mục tiêu không thể được xử lý bằng các bước tiếp theo và không có cách nào để luồng proxy phát hiện lỗi trong cuộc gọi từ xa. Trường hợp sử dụng phổ biến để bỏ qua phần tử Response khi sử dụng ServiceAnnotation: để ghi nhật ký thư đến hệ thống bên ngoài.

 <Response>calloutResponse</Response> 

<Hết thời gian chờ> phần tử

Thời gian tính bằng mili giây mà Chính sách chú thích dịch vụ sẽ chờ phản hồi từ . Bạn không thể đặt giá trị này một cách linh động trong thời gian chạy. Nếu Chú thích dịch vụ hết thời gian chờ, HTTP 500 được trả về, chính sách không thành công và proxy API chuyển sang trạng thái lỗi, như mô tả trong phần Xử lý lỗi.

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; phần tử

Cung cấp thông tin chi tiết về truyền tải như thuộc tính URL, TLS/SSL và HTTP. Xem Tài liệu tham khảo về cấu hình <TargetEndpoint>.

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; phần tử

URL đến dịch vụ được gọi:

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

Bạn có thể cung cấp một phần của URL một cách linh động bằng một biến. Tuy nhiên, phần giao thức của URL, http:// dưới đây, không được do một biến chỉ định. Trong ví dụ tiếp theo, bạn sử dụng một biến để chỉ định giá trị của truy vấn tham số:

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

Hoặc đặt một phần đường dẫn URL bằng một biến:

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

Nếu bạn muốn dùng một biến để chỉ định miền và cổng của URL, hãy dùng một biến chỉ cho miền và cổng và biến thứ hai cho bất kỳ phần nào khác của URL:

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

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; phần tử

Cấu hình TLS/SSL cho dịch vụ phụ trợ. Để được trợ giúp về cấu hình TLS/SSL, hãy xem Định cấu hình TLS từ Edge đến phần phụ trợ (Đám mây và Đám mây riêng tư) và "Cấu hình điểm cuối đích TLS/SSL" trong tài liệu tham khảo về cấu hình 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>

Các thuộc tính truyền tải HTTP đến dịch vụ phụ trợ. Để biết thêm thông tin, hãy xem Tài liệu tham khảo về thuộc tính điểm cuối.

<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; phần tử

Gọi một hoặc nhiều máy chủ mục tiêu và cân bằng tải trên các máy chủ đó. Xem Mục tiêu cuộc gọi máy chủ trong phần Mẫu. Xem thêm bài viết Cân bằng tải trên phần phụ trợ máy chủ. Xem thêm cộng đồng này bài đăng thảo luận về các cách gọi máy chủ mục tiêu từ cả chính sách Chú thích dịch vụ và bằng cách sử dụng Quy tắc tuyến đường.

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

&lt;LocalTargetConnection&gt; phần tử

Chỉ định một proxy cục bộ -- tức là một proxy trong cùng một tổ chức và môi trường -- với mục tiêu của chú thích dịch vụ.

Để xác định rõ hơn mục tiêu, hãy sử dụng phần tử <APIProxy> và <ProxyEndpoint> hoặc phần tử <Path>.

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

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; phần tử

Tên của proxy API là mục tiêu của lệnh gọi cục bộ. Proxy phải ở cùng một nơi tổ chức và môi trường làm proxy thực hiện cuộc gọi.

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

Cùng với phần tử <APIProxy>, hãy thêm phần tử Phần tử <ProxyEndpoint> để chỉ định tên của điểm cuối proxy cần được nhắm mục tiêu cho cuộc gọi.

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

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; phần tử

Tên của điểm cuối proxy phải là mục tiêu của cuộc gọi. Đây là điểm cuối proxy trong proxy API được chỉ định với phần tử <APIProxy>.

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; phần tử

Đường dẫn đến điểm cuối đang được nhắm mục tiêu. Điểm cuối phải tham chiếu đến một proxy trong cùng tổ chức và môi trường làm proxy thực hiện cuộc gọi.

Sử dụng cặp này thay vì cặp <APIProxy>/<ProxyEndpoint> khi bạn không không biết -- hoặc không thể dựa vào -- tên proxy. Lộ trình đó có thể là một mục tiêu đáng tin cậy.

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

Giản đồ

Biến luồng

Các biến luồng hỗ trợ hành vi động của các chính sách và Luồng trong thời gian chạy, dựa trên HTTP tiêu đề, nội dung thư hoặc Ngữ cảnh luồng. Hiện có các biến Luồng được xác định trước sau đây sau khi thực thi chính sách Chú thích dịch vụ. Để biết thêm thông tin về Biến luồng, hãy xem Tài liệu tham khảo về biến.

Chú thích dịch vụ có yêu cầu và phản hồi riêng. Bạn có thể truy cập vào dữ liệu đó thông qua biến. Vì thông điệp chính đang dùng request.* và Tiền tố biến response.*, hãy sử dụng myrequest.* và Tiền tố calloutResponse.* (mặc định trong cấu hình Chú thích dịch vụ) thành nhận dữ liệu tin nhắn riêng cho Chú thích dịch vụ. Ví dụ đầu tiên trong bảng sau cho thấy cách bạn sẽ nhận được tiêu đề HTTP trong Chú thích dịch vụ.

Lỗi

Phần này mô tả các mã lỗi và thông báo lỗi được trả về cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi chính sách này thực thi.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy có chứa chính sách này.

Biến lỗi

Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi khi gặp lỗi

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Ví dụ về quy tắc lỗi

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

Chủ đề có liên quan

• Tạo hoặc sửa đổi thông báo: Chỉ định chính sách về thông báo
• Trích xuất biến: Trích xuất biến chính sách của Google
• Biến: Biến tham khảo
• Cấu hình TLS/SSL
  • Định cấu hình TLS từ Edge đến phần phụ trợ (Đám mây và Đám mây riêng tư)
  • "Cấu hình điểm cuối đích TLS/SSL" trong tài liệu tham khảo về cấu hình proxy API
• Thuộc tính truyền tải HTTP: Tài liệu tham khảo về thuộc tính điểm cuối
• Thay thế cho chú thích dịch vụ: HTTPClient được viết bằng JavaScript, xem Mô hình đối tượng JavaScript