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

Bạn đang xem tài liệu về Apigee Edge.
Hãy xem tài liệu về Apigee X.

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 từ luồng proxy API. Bạn có thể tạo chú thích cho một dịch vụ bên ngoài (chẳng hạn như một điểm cuối dịch vụ RESTful bên ngoài) hoặc các dịch vụ nội bộ (chẳng hạn như một 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 bên ngoài proxy của bạn. Phản hồi từ API của bên thứ ba được phân tích cú pháp và chèn vào thông báo phản hồi của API, giúp làm phong phú và "kết hợp" dữ liệu cho người dùng cuối của ứng dụng. Bạn cũng có thể đưa ra yêu cầu bằng chính sách Chú thích dịch vụ trong luồng yêu cầu, sau đó chuyển thông tin trong 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 thuộc cùng một tổ chức và môi trường với proxy mà bạn đang gọi. Ví dụ: bạn có thể thấy điều này hữu ích khi có proxy cung cấp một số chức năng cấp thấp riêng biệt mà một hoặc nhiều proxy khác sẽ sử dụng. Ví dụ: một proxy hiển thị các thao tác tạo/đọc/cập nhật/xoá với 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.

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 bạn có thể sử dụng chính sách Chú thích dịch vụ trong proxy API của mình. 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 nhằm phân phối dữ liệu vị trí địa lý, 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 với hai chính sách khác: Chỉ định biến thông báo và trích xuất.

• Yêu cầu: Chỉ định thông báo sẽ điền thông báo yêu cầu đã gửi đến dịch vụ 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 nội dung cụ thể.

Thành phần chính sách Chú thích dịch vụ điển hình bao gồm:

1. Chính sách gán thông báo: Tạo thông báo yêu cầu, điền tiêu đề HTTP, tham số truy vấn, đặt động từ HTTP, v.v.
2. Chính sách Chú thích dịch vụ: Tham chiếu đến thông báo do chính sách Chỉ định thông báo tạo, xác định URL đích cho lệnh gọi bên ngoài và đặt tên cho đối tượng phản hồi mà dịch vụ đích 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 này trên Cộng đồng Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Chính sách Trích xuất biến: Thường xác định biểu thức JSONPath hoặc XPath phân tích cú pháp thông báo do Chú thích dịch vụ tạo. Sau đó, chính sách này sẽ đặt các biến chứa giá trị được phân tích cú pháp từ phản hồi của Chú thích dịch vụ.

Xem Sử dụng thành phần chính sách để biết 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 Chỉ định thông báo và trích xuất biến.

Xử lý lỗi tùy chỉnh

Tham chiếu phần tử

Sau đây là các yếu tố và thuộc tính bạn có thể định cấu hình 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>

Thuộc tính <ServiceChú thích>

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

Bảng sau đây mô tả các thuộc tính phổ biến với tất cả các phần tử chính sách chính:

Phần tử <DisplayName>

Sử dụng ngoài thuộc tính name để gắn nhãn chính sách trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng một tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>

Phần tử <Request>

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. Biến này có thể được tạo bởi một chính sách trước đó trong luồng hoặc bạn có thể tạo biến đó ngay 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> giống với chính sách Chỉ định thông báo.

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

Trong ví dụ đơn giản nhất, bạn sẽ truyền một biến chứa thông báo yêu cầu đã được điền trước đó vào 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 vào dịch vụ bên ngoài 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

Phần tử <Request>/<ignoreUnresolvedVariables>

Khi bạn đặt thành true, chính sách này 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> 

Thành phần <Response>

Bao gồ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 để xử lý thêm.

Khi có phần tử này, phần tử này sẽ chỉ định tên của biến chứa thông báo phản hồi nhận được từ dịch vụ bên ngoài. Phản hồi từ mục tiêu chỉ được gán cho biến khi chính sách đọc thành công toàn bộ phản hồi. Nếu lệnh gọi từ xa không thành công vì bất kỳ lý do nào, 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; quá trình thực thi luồng API Proxy sẽ tiếp tục với bất kỳ bước luồng tiếp theo nào. Ngoài ra, để thể hiện rõ rằng không có phần tử Response, phản hồi từ mục tiêu sẽ không có sẵn để xử lý theo 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 lệnh gọi từ xa. Cách sử dụng phổ biến để bỏ qua phần tử Response khi sử dụng ServiceChú thích: để ghi nhật ký thông báo vào hệ thống bên ngoài.

 <Response>calloutResponse</Response> 

Phần tử <Timeout>

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

<Timeout>30000</Timeout>

Phần tử <HTTPTargetConnection>

Cung cấp các chi tiết truyền tải như URL, TLS/SSL và các thuộc tính 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>

Phần tử <HTTPTargetConnection>/<URL>

URL tới dịch vụ đang được gọi:

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

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

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

Hoặc đặt một phần của đường dẫn URL có biến:

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

Nếu bạn muốn sử dụng một biến để chỉ định miền và cổng của URL, hãy chỉ sử dụng một biến cho miền và cổng còn biến thứ hai cho mọi phần khác của URL:

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

Phần tử <HTTPTargetConnection>/<SSLInfo>

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 phần Định cấu hình TLS từ Edge cho phần phụ trợ (Cloud và Cloud Cloud) và "Cấu hình điểm cuối 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>

Thuộc tính truyền tải HTTP sang dịch vụ phụ trợ. Để biết thêm thông tin, xem phần 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>

Phần tử <HTTPTargetConnection>/<Loadbalancer>

Gọi một hoặc nhiều máy chủ mục tiêu và cân bằng tải trên chúng. Xem mẫu Máy chủ đích để gọi trong phần Mẫu. Xem thêm Cân bằng tải trên các máy chủ phụ trợ. Hãy xem thêm bài đăng này trên tab Cộng đồng để thảo luận về những cách gọi cho máy chủ mục tiêu trong cả chính sách Chú thích dịch vụ và 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>

Phần tử <LocalTargetConnection>

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) làm mục tiêu của chú thích dịch vụ.

Để chỉ đị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>

Phần tử <LocalTargetConnection>/<APIProxy>

Tên của một proxy API là mục tiêu của một lệnh gọi cục bộ. Proxy phải ở trong cùng một tổ chức và môi trường với proxy đang 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ử <ProxyEndpoint> để chỉ định tên của điểm cuối proxy sẽ được nhắm mục tiêu cho lệnh gọi.

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

Phần tử <LocalTargetConnection>/<ProxyEndpoint>

Tên của điểm cuối proxy sẽ là đích của cuộc gọi. Đây là điểm cuối proxy trong proxy API được chỉ định bằng phần tử <APIProxy>.

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

Phần tử <LocalTargetConnection>/<Path>

Đườ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 một tổ chức và môi trường với proxy đang thực hiện lệnh gọi.

Hãy sử dụng tên này thay vì một cặp <APIProxy>/<ProxyEndpoint> khi bạn không biết hoặc không thể dựa vào tên proxy. Đường dẫn có thể là mục tiêu đáng tin cậy.

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

Giản đồ

Biến của luồng

Biến Flow cho phép hành vi động của chính sách và Flow trong thời gian chạy dựa trên tiêu đề HTTP, nội dung thông báo hoặc ngữ cảnh Flow. Các biến Flow được xác định trước sau đây có sẵn sau khi chính sách Chú thích dịch vụ được thực thi. Để biết thêm thông tin về biến Flow, hãy xem phần Tham khảo 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 các biến. Vì thông báo chính đang sử dụng tiền tố biến request.* và response.*, hãy sử dụng tiền tố myrequest.* và calloutResponse.* (mặc định trong cấu hình Chú thích dịch vụ) để nhận dữ liệu dành riêng cho Chú thích dịch vụ. Ví dụ đầu tiên trong bảng sau đây cho thấy cách bạn nhận các tiêu đề HTTP trong Chú thích dịch vụ.

Lỗi

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 tin nhắn: Gán chính sách Tin nhắn
• Trích xuất biến: Chính sách trích xuất biến
• Biến: Thông tin tham khảo về biến
• Cấu hình TLS/SSL
  • Định cấu hình TLS từ Edge sang phần phụ trợ (Cloud và Private Cloud)
  • "TLS/SSL Cấu hình điểm cuối" trong Tham chiếu cấu hình proxy API
• Thuộc tính truyền tải HTTP: Tham chiếu 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