使用政策組合

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

以下簡要說明這項政策中的元素。如要進一步瞭解這項政策，請參閱「指派訊息政策」。

• <AssignMessage name>：為這項政策命名。在流程中參照政策時，系統會使用此名稱。
• <AssignTo> - 建立具名變數，並命名為 GeocodingRequest。這個變數會封裝由 Service Call 政策傳送至後端的要求物件。
• <QueryParams>：設定後端 API 呼叫所需的查詢參數。在此情況下，Geocoding API 必須知道地點 (以郵遞區號和國家/地區 ID 表示)。應用程式使用者提供了這項資訊，而我們只需在此處擷取這些資訊。sensor 是 API 的必要參數，且為 true 或 false，而我們在這裡用硬式編碼的方式設為 false。
• <Verb>：在這個案例中，我們會向 API 發出簡單的 GET 要求。
• <AssignVariable>：這些變數會儲存傳遞給 API 的值。在本範例中，稍後可在傳回用戶端的回應中存取變數。

使用 Service Call 傳送要求

政策組成序列的下一步是建立 ServiceCallout 政策。Service 呼叫政策 (如下所示) 會將我們在先前 AssignMessage 政策中建立的要求物件傳送至 Google Geocoding 服務，並將結果儲存在名為 GeocodingResponse 的變數中。

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

以下簡要說明這項政策的各個元素。

• <ServiceCallout> - 跟前一個政策一樣，這項政策有名稱。
• <RequestVariable> - 這是在 AssignMessage 政策中建立的變數。這會封裝傳送至後端 API 的要求。
• <Response> - 此元素會為儲存回應的變數命名。如畫面所示，您之後可以透過「擷取變數」政策存取這個變數。
• <HTTPTargetConnection>：指定後端 API 的目標網址。在本例中，我們指定 API 傳回 JSON 回應。

現在我們有兩項政策，一項用於指定使用後端 API (Google 的 Geocoding API) 所需的要求資訊，第二項則是用來將要求傳送至後端 API。接著，我們會處理回應。

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

ExtractVariable 政策的重要元素如下：

• <ExtractVariables name> - 同樣地，政策名稱在流程中使用時會用來參照政策。
• <Source> - 指定我們在 Service 呼叫政策中建立的回應變數。這是這項政策用來擷取資料的變數。
• <VariablePrefix>：變數前置字串會為這項政策中建立的其他變數指定命名空間。前置字串可以是任何名稱，但 Edge 的預先定義變數定義的保留名稱除外。
• <JSONPayload> - 這個元素會擷取我們感興趣的回應資料，並將資料放入具名變數。事實上，Geocoding API 傳回的資訊比經緯度遠多。不過，這個範例唯一需要的值。您可以在 API 說明文件中，查看 Geocoding API 傳回的 JSON 完整轉譯內容。幾何圖形.location.lat 和 幾何圖形.location.lng 的值只是傳回的 JSON 物件中的兩個欄位之一。

可能並不明顯，但請務必注意，ExtractVariables 會產生兩個變數的名稱，其名稱包含變數前置字元 (地理編碼回應) 和政策中指定的實際變數名稱。這些變數會儲存在 API Proxy 中，如畫面所示，適用於 Proxy 流程中的其他政策。變數包括：

• geocoderesponse.latitude
• geocoderesponse.longitude

大部分工作已完成。我們建立了包含三項政策的組合，這些政策會構成要求、呼叫後端 API，以及剖析傳回的 JSON 資料。在最後的步驟中，我們會將這部分的資料饋送至另一個 AssignMessage 政策，呼叫第二個後端 API (Google Elevation API)，並將混搭資料傳回給應用程式開發人員。

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

如果您檢查 Google Elevation API，就會看到該 API 採用兩個查詢參數。第一個稱為 locations，其值是經緯度 (以半形逗號分隔值)。另一個參數為 sensor，此為必要參數，必須是「true」或「false」。此時要特別注意的是，此處建立的要求訊息不需要服務呼叫。在這個階段，我們不需要從 Service Call 呼叫第二個 API，因為可以透過 Proxy 的 TargetEndpoint，呼叫後端 API。想想看，我們擁有呼叫 Google Elevations API 所需的所有資料。這個步驟產生的要求訊息不需要 Service 呼叫 (因為為主要要求管道產生的要求)，因此只要 Proxy 端點按照您為這個 API Proxy 設定的 RouteRule 就可以轉送到 TargetEndpoint。TargetEndpoint 會管理與遠端 API 的連線。(提醒您，elevation API 的網址是在 TargetEndpoint 的 HTTPConnection 中定義。Elevation API 說明文件。我們先前儲存的 QueryParams (country 和 postalcode) 已不再需要，所以我們會在這裡移除。

短暫暫停：返回流程

您可能會好奇，為何我們不建立另一個 Service 稱 政策。畢竟，我們又建立了新的訊息。這樣訊息如何傳送到目標 (Google Elevation API)？答案位於流程的 <RouteRule> 元素中。<RouteRule> 指定如何處理流程的 <Request> 部分執行後任何剩餘的要求訊息。這個 <RouteRule> 指定的 TargetEndpoint，會指示 API Proxy 將訊息傳送至 http://maps.googleapis.com/maps/api/elevation/xml。

如果您下載了 API Proxy 範例，可以在 doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml 檔案中找到 TargetProxy 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>

現在我們只需要處理來自 Google Elevation API 的回應，就完成了。

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

回應包含應用程式使用者所提供郵遞區號中心的地理編碼位置，以及該地理編碼位置的高度。資料是從兩個後端 API 擷取，會與連結至 API Proxy 的政策進行混搭，然後再透過單一回應傳回用戶端。

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

摘要

這個教戰手冊主題說明如何使用政策組合模式，建立多個後端來源的資料混搭。政策組合是 API Proxy 開發時常用的模式，用於在 API 中新增廣告素材功能。