使用政策組合

<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 的變數。 這個變數會封裝要求物件，並由 ServiceCallout 政策傳送至後端。
• <QueryParams> - 設定後端 API 呼叫所需的查詢參數。在這種情況下，Geocoding API 需要知道地點 (以郵遞區號和國家/地區 ID 表示)。這項資訊是由應用程式使用者提供，我們只是在此擷取。API 需要 sensor 參數，且該參數為 true 或 false，我們在此將其硬式編碼為 false。
• <動詞> - 在這個案例中，我們向 API 提出簡單的 GET 要求。
• <AssignVariable> - 這些變數會儲存傳遞至 API 的值。在本例中，變數稍後會在傳回給用戶端的 回應中存取。

使用 ServiceCallout 傳送要求

政策組合序列的下一個步驟是建立 ServiceCallout 政策。下列 ServiceCallout 政策會將我們在先前的 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> - 與先前的政策相同，這項政策也有名稱。
• <要求變數>：這是您在 AssignMessage 政策中建立的變數。封裝傳送至後端 API 的要求。
• <Response> - 這個元素會命名變數，回應會儲存在該變數中。如您所見，ExtractVariables 政策稍後會存取這個變數。
• <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> - 指定在 ServiceCallout 政策中建立的回應變數。這項政策會從這個變數擷取資料。
• <VariablePrefix> - 變數前置字元會為這項政策中建立的其他變數指定命名空間。前置字串可以是任何名稱，但不能是 Edge 預先定義變數定義的保留名稱。
• <JSONPayload>：這個元素會擷取我們感興趣的回應資料，並將其放入具名變數。事實上，Geocoding API 傳回的資訊遠不只經緯度。不過，這些是這個範例唯一需要的值。如要查看 Geocoding API 傳回的完整 JSON 轉譯內容，請參閱 API 說明文件。geometry.location.lat 和 geometry.location.lng 的值只是傳回 JSON 物件中的眾多欄位之二。

這可能不明顯，但請務必瞭解 ExtractVariables 會產生兩個變數，其名稱由變數前置字串 (geocoderesponse) 和政策中指定的實際變數名稱組成。這些變數會儲存在 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。此時最重要的一點是，我們在這裡建立的要求訊息不需要 ServiceCallout。此時我們不需要從 ServiceCallout 呼叫第二個 API，因為可以從 Proxy 的 TargetEndpoint 呼叫後端 API。仔細想想，我們已經擁有呼叫 Google Elevations API 所需的所有資料。在這個步驟中產生的要求訊息不需要 ServiceCallout，因為這是為主要要求管道產生的要求，因此 ProxyEndpoint 會按照為這個 API Proxy 設定的 RouteRule，將要求轉送至 TargetEndpoint。TargetEndpoint 會管理與遠端 API 的連線。(請注意，高程 API 的網址是在 TargetEndpoint 的 HTTPConnection 中定義。如要瞭解詳情，請參閱 Elevation API 說明文件。我們不再需要先前儲存的 QueryParams (country 和 postalcode)，因此在此處移除。

短暫停頓：返回流程

此時您可能會想，為什麼我們不建立另一個 ServiceCallout 政策。畢竟我們又建立了一則訊息。該訊息如何傳送至目標 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 代理程式開發中常用的模式，可為 API 新增創意功能。