使用政策构成

<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。应用用户提供此信息，我们只需在此处提取即可。sensor 参数是 API 所必需的，其值为 true 或 false，我们在此处将其硬编码为 false。
• <Verb> - 在此示例中，我们向 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 返回的信息远不止纬度和经度。不过，对于此示例，我们只需要这些值。您可以在 API 的文档中查看 Geocoding API 返回的 JSON 的完整呈现效果。geometry.location.lat 和 geometry.location.lng 的值只是返回的 JSON 对象中的众多字段中的两个。

虽然可能不太明显，但重要的是要看到 ExtractVariables 会生成两个变量，这两个变量的名称由变量前缀 (geocoderesponse) 和政策中指定的实际变量名称组成。这些变量存储在 API 代理中，并且可供代理流中的其他政策使用，这一点您稍后会看到。变量如下：

• 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，会发现它需要两个查询参数。 第一个称为 locations，其值为纬度和经度（以逗号分隔的值）。另一个形参是 sensor，它是必需的，必须为 true 或 false。此时需要注意的最重要的一点是，我们在此处创建的请求消息不需要 ServiceCallout。我们无需在此阶段通过 ServiceCallout 调用第二个 API，因为我们可以通过代理的 TargetEndpoint 调用后端 API。仔细想想，我们已经拥有调用 Google Elevations API 所需的所有数据。在此步骤中生成的请求消息不需要 ServiceCallout，因为它是为主要请求流水线生成的请求，因此 ProxyEndpoint 会按照为此 API 代理配置的 RouteRule 将其简单地转发到 TargetEndpoint。TargetEndpoint 管理与远程 API 的连接。（请注意，高程 API 的网址是在 TargetEndpoint 的 HTTPConnection 中定义的。如果您想了解详情，请参阅 Elevation API 文档。之前存储的 QueryParams（即 country 和 postalcode）不再需要，因此我们在此处将其移除。

短暂暂停：回到工作流

此时，您可能会想知道为什么我们不创建另一个 ServiceCallout 政策。毕竟，我们创建了另一条消息。如何将该消息发送到目标 Google 高程 API？答案位于流程的 <RouteRule> 元素中。<RouteRule> 用于指定在执行完流程的 <Request> 部分后，如何处理所有剩余的请求消息。此 <RouteRule> 指定的 TargetEndpoint 会告知 API 代理将消息传递到 http://maps.googleapis.com/maps/api/elevation/xml。

如果您下载了示例 API 代理，则可以在文件 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 高程 API 的响应，就完成了。

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

响应包含应用最终用户提供的邮政编码中心的地理编码位置，以及该地理编码位置的海拔高度。数据从两个后端 API 中检索，通过附加到 API 代理的政策进行混搭，然后以单个响应的形式返回给客户端。

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

摘要

此食谱主题介绍了如何使用政策组合模式来混搭来自多个后端来源的数据。政策组合是 API 代理开发中常用的一种模式，用于为 API 添加创新功能。