Sử dụng cấu trúc của chính sách

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Sau đây là nội dung mô tả ngắn gọn về các yếu tố trong chính sách này. Bạn có thể đọc thêm về chính sách này trong Chính sách về việc chỉ định tin nhắn.

• <AssignMessage name> – Đặt tên cho chính sách này. Tên này được dùng khi chính sách được tham chiếu trong một luồng.
• <AssignTo> – Tạo một biến được đặt tên là GeocodingRequest. Biến này đóng gói đối tượng yêu cầu mà chính sách ServiceCallout sẽ gửi đến phần phụ trợ.
• <QueryParams> – Đặt các tham số truy vấn mà lệnh gọi API phụ trợ cần. Trong trường hợp này, Geocoding API cần biết vị trí, được biểu thị bằng mã bưu chính và mã quốc gia. Người dùng ứng dụng cung cấp thông tin này và chúng tôi chỉ cần trích xuất thông tin đó tại đây. API yêu cầu tham số sensor và tham số này là true hoặc false, chúng ta chỉ cần mã hoá cứng tham số này thành false ở đây.
• <Động từ> – Trong trường hợp này, chúng ta đang thực hiện một yêu cầu GET đơn giản đến API.
• <AssignVariable> – Các biến này lưu trữ những giá trị mà chúng ta đang truyền đến API. Trong ví dụ này, các biến sẽ được truy cập sau trong phản hồi được trả về cho ứng dụng.

Gửi yêu cầu bằng ServiceCallout

Bước tiếp theo trong trình tự tạo chính sách là tạo chính sách ServiceCallout. Chính sách ServiceCallout (được liệt kê bên dưới) sẽ gửi đối tượng yêu cầu mà chúng ta đã tạo trong chính sách AssignMessage trước đó đến dịch vụ Google Geocoding và lưu kết quả vào một biến có tên là GeocodingResponse.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Sau đây là nội dung mô tả ngắn gọn về các yếu tố của chính sách này.

• <ServiceCallout> – Giống như chính sách trước, chính sách này cũng có tên.
• <Request variable> – Đây là biến được tạo trong chính sách AssignMessage. Nó đóng gói yêu cầu gửi đến API phụ trợ.
• <Response> – Phần tử này đặt tên cho một biến mà phản hồi được lưu trữ trong đó. Như bạn sẽ thấy, biến này sẽ được truy cập sau đó bằng chính sách ExtractVariables.
• <HTTPTargetConnection> – Chỉ định URL mục tiêu của API phụ trợ. Trong trường hợp này, chúng ta chỉ định rằng API sẽ trả về một phản hồi JSON.

Giờ đây, chúng ta có hai chính sách, một chính sách chỉ định thông tin yêu cầu cần thiết để sử dụng API phụ trợ (Geocoding API của Google) và chính sách thứ hai thực sự gửi yêu cầu đến API phụ trợ. Tiếp theo, chúng ta sẽ xử lý phản hồi.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Các phần tử chính của chính sách ExtractVariable là:

• <ExtractVariables name> – Tên chính sách được dùng để tham chiếu đến chính sách khi chính sách đó được dùng trong một luồng.
• <Source> – Chỉ định biến phản hồi mà chúng ta đã tạo trong chính sách ServiceCallout. Đây là biến mà chính sách này trích xuất dữ liệu.
• <VariablePrefix> – Tiền tố biến chỉ định một không gian tên cho các biến khác được tạo trong chính sách này. Tiền tố có thể là bất kỳ tên nào, ngoại trừ những tên dành riêng do các biến được xác định trước của Edge xác định.
• <JSONPayload> – Phần tử này truy xuất dữ liệu phản hồi mà chúng ta quan tâm và đặt dữ liệu đó vào các biến được đặt tên. Trên thực tế, Geocoding API trả về nhiều thông tin hơn so với vĩ độ và kinh độ. Tuy nhiên, đây là những giá trị duy nhất chúng ta cần cho mẫu này. Bạn có thể xem bản kết xuất hoàn chỉnh của JSON do Geocoding API trả về trong tài liệu của API. Các giá trị của geometry.location.lat và geometry.location.lng chỉ là hai trong số nhiều trường trong đối tượng JSON được trả về.

Có thể bạn không thấy rõ, nhưng điều quan trọng là bạn phải thấy rằng ExtractVariables tạo ra 2 biến có tên bao gồm tiền tố biến (geocoderesponse) và tên biến thực tế được chỉ định trong chính sách. Các biến này được lưu trữ trong API proxy và sẽ có sẵn cho các chính sách khác trong luồng proxy, như bạn sẽ thấy. Các biến số là:

• geocoderesponse.latitude
• geocoderesponse.longitude

Hầu hết công việc đã hoàn tất. Chúng ta đã tạo một thành phần gồm 3 chính sách tạo thành một yêu cầu, gọi một API phụ trợ và phân tích cú pháp dữ liệu JSON được trả về. Trong các bước cuối cùng, chúng ta sẽ truyền dữ liệu từ phần này của quy trình vào một chính sách AssignMessage khác, gọi API phụ trợ thứ hai (Google Elevation API) và trả dữ liệu đã kết hợp cho nhà phát triển ứng dụng.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Nếu kiểm tra Google Elevation API, bạn sẽ thấy API này có 2 tham số truy vấn. Tham số đầu tiên có tên là locations và giá trị của tham số này là vĩ độ và kinh độ (các giá trị được phân tách bằng dấu phẩy). Tham số còn lại là sensor, đây là tham số bắt buộc và phải là true hoặc false. Điều quan trọng nhất cần lưu ý tại thời điểm này là thông báo yêu cầu mà chúng ta tạo ở đây không yêu cầu ServiceCallout. Tại thời điểm này, chúng ta không cần gọi API thứ hai từ ServiceCallout vì có thể gọi API phụ trợ từ TargetEndpoint của proxy. Nếu bạn nghĩ về điều đó, chúng tôi có tất cả dữ liệu cần thiết để gọi Google Elevations API. Thông báo yêu cầu được tạo trong bước này không yêu cầu ServiceCallout, vì yêu cầu được tạo cho quy trình yêu cầu chính, nên sẽ chỉ được ProxyEndpoint chuyển tiếp đến TargetEndpoint, theo RouteRule được định cấu hình cho proxy API này. TargetEndpoint quản lý kết nối với API từ xa. (Nhớ lại rằng URL cho API độ cao được xác định trong HTTPConnection cho TargetEndpoint. Tài liệu về Elevation API nếu bạn muốn biết thêm. QueryParams mà chúng ta đã lưu trữ trước đó, country và postalcode, không còn cần thiết nữa, vì vậy, chúng ta sẽ xoá chúng ở đây.

Tạm dừng một chút: Quay lại quy trình

Đến đây, có thể bạn sẽ thắc mắc tại sao chúng tôi không tạo một chính sách ServiceCallout khác. Sau tất cả, chúng tôi đã tạo một thông báo khác. Làm cách nào để gửi thông báo đó đến đích đến là Google Elevation API? Câu trả lời nằm trong phần tử <RouteRule> của luồng. <RouteRule> chỉ định việc cần làm với mọi thông báo yêu cầu còn lại sau khi phần <Request> của quy trình đã thực thi. TargetEndpoint do <RouteRule> này chỉ định sẽ cho biết proxy API cần gửi thông báo đến http://maps.googleapis.com/maps/api/elevation/xml.

Nếu đã tải API proxy mẫu xuống, bạn có thể tìm thấy TargetProxy XML trong tệp doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Giờ đây, chúng ta chỉ cần xử lý phản hồi từ Google Elevation API là xong.

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

Phản hồi bao gồm vị trí được mã hoá địa lý cho tâm của mã bưu chính do người dùng cuối ứng dụng cung cấp, kết hợp với độ cao tại vị trí được mã hoá địa lý đó. Dữ liệu được truy xuất từ 2 API phụ trợ, kết hợp với các chính sách được đính kèm vào proxy API và được trả về cho ứng dụng khách trong một phản hồi duy nhất.

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

Tóm tắt

Chủ đề này trong sổ tay hướng dẫn giải thích cách sử dụng mẫu thành phần chính sách để tạo một bản kết hợp dữ liệu từ nhiều nguồn phụ trợ. Thành phần chính sách là một mẫu phổ biến được dùng trong quá trình phát triển proxy API để thêm chức năng sáng tạo vào API của bạn.