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 từ quy trình proxy API. Bạn có thể tạo chú thích cho dịch vụ bên ngoài (chẳng hạn như điểm cuối của dịch vụ RESTful bên ngoài) hoặc các dịch vụ nội bộ (chẳng hạn như proxy API trong cùng 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 một API 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, làm phong phú và "hợp nhất" dữ liệu cho người dùng cuối của ứng dụng. Bạn cũng có thể gửi yêu cầu bằng chính sách Chú thích dịch vụ trong quy trình yêu cầu, sau đó truyề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 có thể gọi một proxy ở cùng tổ chức và môi trường với proxy mà bạn đang dùng để gọi. Ví dụ: bạn có thể thấy điều này hữu ích khi có một 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á bằng 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.

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. Ví dụ: bạn có thể định cấu hình proxy API để thực hiện cuộc gọi tới một dịch vụ bên ngoài nhằm cung cấp 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 với 2 chính sách khác: Chỉ định thông báo và Trích xuất biến.

• Request (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 các biến 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 thông thường của chính sách Chú thích dịch vụ bao gồm:

1. Gán chính sách Thông báo: Tạo một 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 một thông báo được tạo theo chính sách Chỉ định thông báo, xác định URL mục tiêu 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ụ 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 về 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 ra. 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 Chú thích dịch vụ.

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

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

Tham chiếu phần tử

Dưới đây là các phần tử và thuộc tính mà bạn có thể thiết lập trong 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 <ServiceTool>

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

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

Phần tử <DisplayName>

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

<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ằng 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> cũng giống như trong chính sách Chỉ định thông báo.

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 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 truyền một biến chứa thông báo yêu cầu đã được điền trước đó trong luồng proxy API:

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

Hoặc bạn có thể điền sẵn thông báo yêu cầu được gửi đến 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 đặ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> 

Phần tử <Response>

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

Khi có mặt, 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 gì, chính sách sẽ trả về một lỗi.

Nếu bạn bỏ qua phần tử này, proxy API sẽ không chờ phản hồi; việc thực thi luồng Proxy API sẽ tiếp tục với mọi bước tiếp theo trong quy trình. Ngoài ra, để nêu 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ý qua 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 thông điệp đến một 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ẽ chờ phản hồi từ mục tiêu. Bạn không thể đặt giá trị này động 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 hoạt độ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 thông tin truyền tải như các thuộc tính URL, TLS/SSL và HTTP. Hãy 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 biến cho một phần của URL theo cách linh động. Tuy nhiên, một biến không thể chỉ đị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 một 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 đườ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 sử dụng một biến để chỉ định miền và cổng của URL, hãy sử dụng một biến cho miền và cổng, còn một 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>

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 đến phần phụ trợ (Đám mây và Đám mây riêng tư) 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>

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>

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

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ẫu Máy chủ đích của lệnh gọi trong phần Mẫu. Xem thêm bài viết Cân bằng tải trên các máy chủ phụ trợ. Hãy xem thêm bài đăng trên thẻ Cộng đồng này để thảo luận về cách gọi máy chủ đích từ cả chính sách Chú thích dịch vụ và quy tắc định tuyến.

<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 tổ chức và môi trường) làm mục tiêu của chú thích dịch vụ.

Để chỉ định thêm 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 cuộc gọi cục bộ. Proxy phải nằm trong cùng một tổ chức và môi trường với 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ử <ProxyEndpoint> để chỉ định tên của điểm cuối proxy cần nhắm đến cho lệnh gọi.

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

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

Tên của điểm cuối proxy phải là mục tiêu của cuộc gọi. Đây là một đ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 đến. Đ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 thực hiện lệnh gọi.

Hãy sử dụng cặp này thay vì 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ộ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 cho phép 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 tiêu đề HTTP, nội dung thông báo hoặc ngữ cảnh Luồng. Bạn có thể sử dụng các biến Flow đượ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 Flow, hãy xem bài viết 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 và 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.*, nên hãy sử dụng tiền tố myrequest.* và calloutResponse.* (giá trị mặc định trong cấu hình Chú thích dịch vụ) để lấy dữ liệu thông báo dành 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 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 đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem 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 thực thi chính sách.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy 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 Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi 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 sách chỉ định thông báo
• Trích xuất biến: Chính sách về Trích xuất biến
• Biến: Tham chiếu biến
• 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 TLS/TLS" trong Tài liệu tham khảo 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 thiết bị đầu cuối
• Thay thế cho Chú thích dịch vụ: HTTPClient được viết bằng JavaScript, hãy xem mô hình đối tượng JavaScript