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

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

Trong chủ đề này, bạn sẽ tìm hiểu cách tạo một ứng dụng kết hợp dữ liệu bằng cách sử dụng cấu trúc chính sách. Thành phần chính sách là một mẫu proxy Apigee cho phép bạn kết hợp kết quả từ nhiều phần phụ trợ mục tiêu thành một phản hồi duy nhất bằng cách sử dụng chính sách.

Để biết thông tin tổng quan chung về cấu trúc chính sách, hãy xem bài viết "Mẫu cấu thành chính sách" trong API Proxy Cookbook mẫu.

Tải xuống và dùng thử mã mẫu

Giới thiệu ví dụ về sổ tay nấu ăn này

Ví dụ về sổ tay nấu ăn này minh hoạ một mẫu proxy API có tên là thành phần chính sách. Mẫu này cung cấp một cách (có nhiều cách khác) để kết hợp dữ liệu từ nhiều nguồn phụ trợ. Một cách tổng quát hơn, chủ đề này trình bày cách kết hợp và xâu chuỗi các chính sách với nhau sẽ tạo ra kết quả mong muốn. Để biết tổng quan chung về mẫu này cũng như các mẫu có liên quan khác, hãy xem Cẩm nang về proxy API mẫu.

Ví dụ được thảo luận ở đây sử dụng cấu trúc chính sách để kết hợp dữ liệu từ hai chính sách riêng biệt này API công khai:

  • Mã hoá địa lý của Google API: API này chuyển đổi các địa chỉ (như "1600 Amphitheatre Parkway, Mountain View, CA") thành toạ độ địa lý (như vĩ độ 37,423021 và kinh độ -122,083739).
  • Độ cao của Google API API này cung cấp giao diện đơn giản để truy vấn vị trí trên trái đất để đo độ cao . Trong ví dụ này, toạ độ được trả về từ API mã hoá địa lý sẽ được sử dụng làm thông tin đầu vào vào API này.

Nhà phát triển ứng dụng sẽ gọi proxy API này bằng hai tham số truy vấn: mã bưu chính và quốc gia Mã nhận dạng:

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

Phản hồi là đối tượng JSON bao gồm vị trí được mã hoá địa lý (vĩ độ/kinh độ) cho tâm khu vực mã bưu chính được cung cấp kết hợp với cao độ tại mã vạch được đánh dấu địa lý đó vị trí. 

{  
   "ElevationResponse":{  
      "status":"OK",
      "result":{  
         "location":{  
            "lat":"39.7500713",
            "lng":"-74.1357407"
         },
         "elevation":"0.5045232",
         "resolution":"76.3516159"
      }
   }
}

Trước khi bắt đầu

Nếu bạn muốn đọc thông tin tổng quan ngắn gọn về mẫu cấu trúc chính sách, hãy xem phần "Chính sách mẫu kết hợp" trong API Proxy Cookbook mẫu.

Trước khi tìm hiểu ví dụ về sổ tay nấu ăn này, bạn cũng chắc hẳn đã nắm rõ những kiến thức cơ bản sau đây các khái niệm:

  • Chính sách là gì và cách đính kèm chính sách vào proxy. Để giới thiệu sơ lược về các chính sách, hãy xem bài viết Sự kiện phát trực tiếp chính sách của Google?.
  • Cấu trúc của luồng proxy API, như giải thích trong Định cấu hình luồng. Flow cho phép bạn chỉ định trình tự thực thi các chính sách bằng proxy API. Trong ví dụ này, có vài các chính sách này được tạo và thêm vào quy trình của proxy API.
  • Cách sắp xếp dự án proxy API trên hệ thống tệp của bạn, như giải thích trong Tài liệu tham khảo về cấu hình proxy API. Chủ đề sổ tay nấu ăn này minh hoạ sự phát triển của địa phương (tệp dựa trên hệ thống) thay vì phát triển trên đám mây, trong đó bạn có thể sử dụng giao diện người dùng quản lý để phát triển proxy API.
  • Sử dụng phương thức xác thực khoá API. Đây là hình thức bảo mật dựa trên ứng dụng đơn giản nhất mà bạn có thể định cấu hình cho một API. Để biết thêm thông tin, hãy xem API khoá. Bạn cũng có thể đi qua phần Bảo mật một API bằng cách yêu cầu khoá API.
  • Kiến thức thực hành về XML. Trong ví dụ này, chúng ta xây dựng proxy API và với các tệp XML nằm trên hệ thống tệp.

Nếu đã tải mã mẫu xuống, bạn có thể xác định vị trí tất cả các tệp được thảo luận trong bài viết này chủ đề trong thư mục mẫu mashup-policy-cookbook. Các phần sau hãy thảo luận chi tiết về mã mẫu đó.

Thuận theo dòng chảy tự nhiên

Trước khi chuyển đến các chính sách này, hãy xem quy trình chính trong ví dụ này Proxy API. Luồng XML, được hiển thị bên dưới, cho chúng ta biết nhiều thông tin về proxy này, các chính sách mà nó sử dụng và nơi gọi của những chính sách đó.

Trong tệp tải xuống mẫu, bạn có thể tìm thấy XML này trong tệp doc-samples/policy-mashup-cookbook/apiproxy/proxies/default.xml.

<ProxyEndpoint name="default">
  <Flows>
    <Flow name="default">
      <Request>
            <!-- Generate request message for the Google Geocoding API -->
            <Step><Name>GenerateGeocodingRequest</Name></Step>
            <!-- Call the Google Geocoding API -->
            <Step><Name>ExecuteGeocodingRequest</Name></Step>
            <!-- Parse the response and set variables -->
            <Step><Name>ParseGeocodingResponse</Name></Step>
            <!-- Generate request message for the Google Elevation API -->
            <Step><Name>AssignElevationParameters</Name></Step>
      </Request>
      <Response>
            <!-- Parse the response message from the Elevation API -->
            <Step><Name>ParseElevationResponse</Name></Step>
            <!-- Generate the final JSON-formatted response with JavaScript -->
            <Step><Name>GenerateResponse</Name></Step>
      </Response>
    </Flow>
  </Flows>

  <HTTPProxyConnection>
    <!-- Add a base path to the ProxyEndpoint for URI pattern matching-->
    <BasePath>/policy-mashup-cookbook</BasePath>
    <!-- Listen on both HTTP and HTTPS endpoints -->
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <!-- Connect ProxyEndpoint to named TargetEndpoint under /targets -->
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Dưới đây là tóm tắt các phần tử của luồng.

  • &lt;Request&gt; – <Request> phần tử bao gồm một số &lt;Step&gt; phần tử. Mỗi bước yêu cầu một trong các chính sách mà chúng tôi sẽ tạo từ các bước còn lại về chủ đề này. Các chính sách này liên quan đến việc tạo, gửi thông báo yêu cầu và phân tích cú pháp phản hồi. Khi kết thúc chủ đề này, bạn sẽ hiểu rõ vai trò của từng yếu tố Google Cloud.
  • &lt;Response&gt; - <Response> cũng bao gồm <Các bước>. Các bước này cũng gọi các chính sách chịu trách nhiệm xử lý bản phản hồi từ điểm cuối mục tiêu (API Nâng cao của Google).
  • &lt;HttpProxyConnection&gt; – Phần tử này chỉ định thông tin chi tiết về cách ứng dụng sẽ kết nối với proxy API này, bao gồm cả <BasePath>, chỉ định cách API này sẽ được gọi.
  • &lt;RouteRule&gt; - Phần tử này chỉ định điều gì sẽ xảy ra ngay lập tức sau khi thư yêu cầu đến được xử lý. Trong trường hợp này, TargetEndpoint sẽ được gọi. Chúng ta sẽ thảo luận thêm về bước quan trọng này sau trong chủ đề này.

Tạo chính sách

Các phần sau đây thảo luận về từng chính sách tạo nên cấu trúc chính sách này ví dụ:

Tạo AttributionMessage đầu tiên chính sách

Chính sách AssignMessage đầu tiên, được liệt kê bên dưới, tạo một thông báo yêu cầu sẽ được gửi đến Nhóm mã hoá địa lý của Google .

Hãy bắt đầu với mã chính sách và sau đó chúng tôi sẽ giải thích các thành phần chi tiết hơn. Trong để tải xuống mẫu, bạn có thể tìm thấy XML này trong tệp doc-samples/policy-mashup-cookbook/apiproxy/policies/GenerateGeocodingRequest.xml.

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

Dưới đâ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ề vấn đề này chính sách trong phần Chỉ định Chính sách về tin nhắn.

  • <AssignmentMessage name> – Đặt tên cho chính sách này. Tên là được dùng khi chính sách này được tham chiếu trong một luồng.
  • &lt;AssignTo&gt; – Tạo một biến được đặt tên có tên là GeocodesRequest. Biến này đóng gói đối tượng yêu cầu sẽ được gửi đến phần phụ trợ bởi Chính sách về chú thích dịch vụ.
  • &lt;QueryParams&gt; – Đặt các tham số truy vấn mà lệnh gọi API phụ trợ. Trong trường hợp này, API mã hoá địa lý cần biết vị trí, được thể hiện 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ỉ trích xuất nó ở đây. Tham số sensor được API yêu cầu và true hoặc false. Chúng tôi chỉ mã hoá cứng để biến nó thành false (sai) ở đây.
  • &lt;Verb&gt; – Trong trường hợp này, chúng ta thực hiện một yêu cầu GET đơn giản đến API.
  • &lt;AssignVariable&gt; - Các biến này lưu trữ các giá trị mà chúng ta đang có đang truyền đến API. Trong ví dụ này, các biến sẽ được truy cập vào lúc khác trong phản hồi được trả về máy khách.

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

Bước tiếp theo trong trình tự soạn chính sách là tạo chính sách ServiceCallout. Chiến lược phát hành đĩa đơn Chính sách ServiceAnnotation (như trong danh sách 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 AttributionMessage trước đó cho dịch vụ Mã hoá địa lý của Google và lưu kết quả trong một được gọi là GeocodesResponse.

Như đã đề cập ở trên, trước tiên, hãy cùng xem xét mã nguồn. Sau đây là nội dung giải thích chi tiết. Bạn có thể đọc tìm hiểu thêm về chính sách này trong phần Chú thích dịch vụ . Trong tệp tải xuống mẫu, bạn có thể tìm thấy XML này trong tệp doc-samples/policy-mashup-cookbook/apiproxy/policies/ExecuteGeocodingRequest.xml.

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

Dưới đây là nội dung mô tả ngắn gọn về các thành phần của chính sách này.

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

Hiện tại, chúng tôi có hai chính sách, một chính sách nêu rõ thông tin về yêu cầu cần thiết để sử dụng phụ trợ API (API Mã hoá địa lý của Google) và API 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.

Phân tích cú pháp phản hồi bằng ExtractVariables

Chính sách ExtractVariables cung cấp một cơ chế đơn giản để phân tích cú pháp nội dung từ thông báo phản hồi nhận được theo chính sách ServiceAnnotation. Có thể dùng ExtractVariables để phân tích cú pháp JSON hoặc XML hoặc có thể được dùng để trích xuất nội dung từ đường dẫn URI, tiêu đề HTTP, truy vấn tham số và thông số biểu mẫu.

Dưới đây là danh sách chính sách ExtractVariables. Bạn có thể đọc thêm về chính sách này trong Trích xuất biến . Trong tệp tải xuống mẫu, bạn có thể tìm thấy XML này trong tệp doc-samples/policy-mashup-cookbook/apiproxy/policies/ParseGeocodingResponse.xml.

<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 thành phần chính của chính sách ExtractVariable là:

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

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

  • geocoderesponse.latitude
  • geocoderesponse.longitude

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

Tạo thuộc tính thứ hai yêu cầu bằng AttributionMessage

Chính sách AttributionMessage sau đây sử dụng các biến được trả về từ phần phụ trợ đầu tiên (Google Mã hoá địa lý) mà chúng tôi lưu trữ và đưa chúng vào một yêu cầu dành cho API thứ hai (Google Độ cao). Như đã lưu ý trước đó, các biến này là mã địa lý phản hồi.latitude và geocoderesponse.longitude.

Trong tệp tải xuống mẫu, bạn có thể tìm thấy XML này trong tệp doc-samples/policy-mashup-cookbook/apiproxy/policies/AssignElevationParameters.xml.

<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 API Độ cao của Google, bạn sẽ thấy rằng API này có 2 tham số truy vấn. Giá trị đầu tiên là locations và giá trị của nó là vĩ độ và kinh độ (giá trị được phân tách bằng dấu phẩy). Tham số khác là sensor, bắt buộc và phải là đúng hoặc sai. Điều quan trọng nhất cần lưu ý tại thời điểm này là yêu cầu thông báo chúng tôi tạo ở đây không yêu cầu phải có Chú thích dịch vụ. Chúng ta không cần gọi hàm thứ hai API từ ServiceAnnotation tại thời điểm này vì chúng ta có thể gọi API phụ trợ từ Điểm cuối mục tiêu. Nếu bạn suy nghĩ về điều này, chúng tôi có tất cả dữ liệu cần thiết để gọi là Độ cao trên Google API Thông báo yêu cầu được tạo ở bước này không cần phải có ServiceAnnotation, vì được tạo cho quy trình yêu cầu chính, nên sẽ chỉ được chuyển tiếp bởi ProxyEndpoint đến TargetEndpoint, tuân 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. (Hãy nhớ rằng URL cho API độ cao được xác định trong HTTPConnection cho TargetEndpoint. API nâng cao 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 tôi sẽ xoá chúng vào đây.

Tạm dừng nhanh: Quay lại quy trình

Tại thời điểm này, bạn có thể thắc mắc tại sao chúng tôi không tạo một chính sách khác về Chú thích dịch vụ. Sau tất cả, chúng tôi đã tạo một thông báo khác. Làm cách nào để thông điệp đó được gửi đến mục tiêu, gói thuê bao Google API nâng cao? Câu trả lời có trong <RouteRule> phần tử của luồng. &lt;RouteRule&gt; 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 <Request> một phần của luồng đã thực thi. TargetEndpoint được chỉ định bằng <RouteRule> này cho Proxy API để gửi thông báo thành http://maps.googleapis.com/maps/api/elevation/xml.

Nếu đã tải proxy API mẫu xuống, bạn có thể tìm thấy XML TargetProxy 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>

Hiện tại, chúng tôi chỉ cần xử lý phản hồi từ API Độ cao của Google và chúng tôi xong.

Chuyển đổi phản hồi từ XML sang JSON

Trong ví dụ này, phản hồi từ API nâng cao của Google được trả về dưới dạng XML. Đối với "thêm tín dụng", hãy thêm một chính sách nữa vào thuộc tính tổng hợp để chuyển đổi phản hồi từ XML thành JSON.

Ví dụ này sử dụng chính sách JavaScript có tên GenerateResponse, kèm theo tệp tài nguyên chứa mã JavaScript để thực hiện chuyển đổi. Hiển thị bên dưới là định nghĩa chính sách GenerateResponse:

<Javascript name="GenerateResponse" timeout="10000">
  <ResourceURL>jsc://GenerateResponse.js</ResourceURL>
</Javascript>

Tệp tài nguyên GenerateResponse.js bao gồm JavaScript được dùng để thực hiện chuyển đổi. Bạn có thể xem mã đó trong tệp doc-samples/policy-mashup-cookbook/apiproxy/resources/JSC/GenerateResponse.js.

Apigee cũng cung cấp một chính sách có sẵn là XMLToJSON, để chuyển đổi XML sang JSON. Bạn có thể chỉnh sửa ProxyEndpoint để sử dụng chính sách xmltojson hiển thị bên dưới thay thế. 

<XMLToJSON name="xmltojson">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Kiểm thử ví dụ

Nếu bạn chưa thực hiện việc này, hãy thử tải xuống, triển khai và chạy Mẫu policy-mashup-cookbook mà bạn có thể tìm thấy trong thư mụcdoc-samples trên kho lưu trữ mẫu Apigee Edge trên GitHub. Chỉ làm theo hướng dẫn trong tệp README trong thư mục Policy-mashup-cookbook. Hoặc hãy làm theo hướng dẫn ngắn gọn ở đây: Sử dụng proxy API mẫu.

Tóm lại, bạn có thể gọi API tổng hợp như sau. Thay thế {myorg} của bạn bằng tên tổ chức:

$ 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ý của trung tâm mã bưu chính do bên cung cấp người dùng cuối của ứng dụng, kết hợp với độ cao tại vị trí được mã hoá địa lý đó. Dữ liệu đã truy xuất từ hai API phụ trợ, kết hợp với các chính sách đi kèm với proxy API và trả về máy 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ủ đề sổ tay nấu ăn này giải thích cách sử dụng mẫu cấu trúc chính sách để tạo ứng dụng kết hợp dữ liệu từ nhiều nguồn phụ trợ. Cấu trúc chính sách là một mẫu phổ biến được dùng trong API phát triển proxy để thêm chức năng quảng cáo vào API của bạn.