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

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. Thông tin

Nội dung

Chính sách Lời gọi 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ể thực hiện lệnh gọi đến 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 sẽ thực hiện một lệnh gọi đến API của bên thứ ba nằm bên ngoài proxy của bạn. Phản hồi từ API của bên thứ ba sẽ đượ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à "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 cách sử dụ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 API proxy.
• Trong một trường hợp sử dụng khác, bạn gọi một proxy nằm trong cùng 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ó một proxy cung cấp một số chức năng rời rạc ở cấp thấp 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 các ứ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 về dịch vụ

Có nhiều trường hợp bạn có thể sử dụng chính sách Lời gọi dịch vụ trong proxy API. Ví dụ: bạn có thể định cấu hình một proxy API để thực hiện các 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ý, đá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.

Thường thì lệnh gọi này được dùng với 2 chính sách khác: Chỉ định thông báo và Trích xuất biến.

• Yêu cầu: Assign Message (Chỉ định thông báo) sẽ điền sẵn thông báo yêu cầu được gửi đến dịch vụ từ xa.

• Phản hồi: Extract Variables (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 về dịch vụ thường bao gồm:

1. Chính sách Chỉ định thông báo: Tạo thông báo yêu cầu, điền sẵ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 do chính sách Chỉ định thông báo tạo ra, 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 vào bộ nhớ đệm các phản hồi của Lời gọi dịch vụ, như mô tả trong chuỗi thảo luận này trên Cộng đồng Apigee: Làm cách nào để lưu trữ kết quả của chính sách ServiceCallout trong bộ nhớ đệm và sau đó truy xuất kết quả đó từ bộ nhớ đệm?.
3. Chính sách Trích xuất biến: Thường xác định một biểu thức JSONPath hoặc XPath phân tích cú pháp thông báo do Lệnh gọi dịch vụ tạo. Sau đó, chính sách sẽ đặt các biến chứa các giá trị được phân tích cú pháp từ phản hồi Lời gọi dịch vụ.

Hãy xem phần Sử dụng thành phần chính sách để biết một proxy API mẫu hoàn chỉnh sử dụng chính sách Lệnh gọi dịch vụ cùng với các 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ể định cấu hình trên 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 <ServiceCallout>

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

&lt;DisplayName&gt; 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>

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 này nội tuyến 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 thẻ <Remove>, <Copy>, <Add> và <Set> giống với cú pháp cho 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 phân giải được thông báo yêu cầu hoặc thông báo yêu cầu 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 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 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 được đặ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>

Hãy thêm phần tử này khi logic của proxy API yêu cầu phản hồi từ lệnh gọi từ xa để xử lý thêm.

Khi phần tử này xuất hiện, nó sẽ chỉ định tên của biến sẽ 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ừ đích đến chỉ được chỉ định 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, chính sách sẽ trả về lỗi.

Nếu bạn bỏ qua phần tử này, thì API Proxy sẽ không đợi phản hồi; quá trình thực thi luồng API Proxy sẽ tiếp tục với mọi bước tiếp theo trong luồng. Ngoài ra, để nêu rõ, nếu không có phần tử Response, phản hồi từ mục tiêu sẽ không được các bước tiếp theo xử lý và không có cách nào để luồng proxy phát hiện lỗi trong lệnh gọi từ xa. Một trường hợp sử dụng phổ biến để bỏ qua phần tử Response khi dùng ServiceCallout: ghi lại thông báo vào 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 theo cách linh động trong thời gian chạy. Nếu Lời gọi 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 thông tin chi tiết về việc truyền tải, chẳng hạn như URL, TLS/SSL và các thuộc tính HTTP. Hãy xem thông tin 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 đến 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 của URL một cách linh động bằng một biến. Tuy nhiên, bạn không thể chỉ định phần giao thức của URL (http:// bên dưới) bằng một biến. Trong ví dụ tiếp theo, bạn sẽ dùng một biến để chỉ định giá trị của một 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 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 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 đến phần phụ trợ (Đám mây và Đám mây riêng tư) và "Cấu hình TargetEndpoint 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 cho dịch vụ phụ trợ. Để biết thêm thông tin, hãy xem phần Tài liệu tham khảo về các thuộc tính của đ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ủ đích và thực hiện cân bằng tải trên các máy chủ đó. Xem mẫu Gọi máy chủ đích trong phần Mẫu. Xem thêm phần Cân bằng tải trên các máy chủ phụ trợ. Bạn cũng có thể xem bài đăng này trên cộng đồng để tìm hiểu các cách gọi máy chủ đích từ cả chính sách Chú thích dịch vụ và bằng cách sử dụng 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 các 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 thuộc cùng một tổ chức và môi trường với proxy thực hiện lệnh 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 được 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 các lệnh 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 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 này 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. Các biến Flow được xác định trước sau đây sẽ có sẵn sau khi chính sách Lời gọi dịch vụ thực thi. Để biết thêm thông tin về các biến trong luồng, hãy xem phần 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, đồng thời 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.* (các giá trị mặc định trong cấu hình Chú thích dịch vụ) để nhận 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 đây cho biết cách bạn nhận tiêu đề HTTP trong Lệnh gọi 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 tin nhắn: Chỉ định chính sách về tin nhắn
• Trích xuất các biến: Chính sách Trích xuất các 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ợ (Cloud và Private Cloud)
  • "TLS/SSL TargetEndpoint Configuration" (Cấu hình TargetEndpoint TLS/SSL) trong Tài liệu tham khảo về cấu hình của API proxy
• 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
• Giải pháp 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