Como usar a composição de política

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

Confira uma breve descrição dos elementos dessa política. Leia mais sobre essa política em Política AssignMessage.

• <AssignMessage name> : atribui um nome a essa política. O nome é usado quando a política é referenciada em um fluxo.
• <AssignTo> : cria uma variável nomeada chamada GeocodingRequest. Essa variável encapsula o objeto de solicitação que será enviado ao back-end pela política ServiceCallout.
• <QueryParams> : define os parâmetros de consulta necessários para a chamada de API de back-end. Nesse caso, a API Geocoding precisa saber o local, que é expresso com um código postal e um ID do país. O usuário do app fornece essas informações, e nós apenas as extraímos aqui. O parâmetro sensor é exigido pela API e é verdadeiro ou falso. Nós apenas o codificamos como falso aqui.
• <Verb> : nesse caso, estamos fazendo uma solicitação GET simples para a API.
• <AssignVariable> : essas variáveis armazenam os valores que estamos transmitindo para a API. Neste exemplo, as variáveis serão acessadas mais tarde na resposta retornada ao cliente.

Enviar a solicitação com ServiceCallout

A próxima etapa na sequência de composição de políticas é criar uma política ServiceCallout. A política ServiceCallout, listada abaixo, envia o objeto de solicitação que criamos na política AssignMessage anterior para o serviço Google Geocoding e salva o resultado em uma variável chamada GeocodingResponse.

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

Confira uma breve descrição dos elementos dessa política.

• <ServiceCallout> : como na política anterior, essa tem um nome.
• <Request variable> : essa é a variável criada na política AssignMessage. Ela encapsula a solicitação que vai para a API de back-end.
• <Response> : esse elemento nomeia uma variável em que a resposta é armazenada. Como você verá, essa variável será acessada mais tarde pela política ExtractVariables.
• <HTTPTargetConnection> : especifica o URL de destino da API de back-end. Nesse caso, especificamos que a API retorne uma resposta JSON.

Agora temos duas políticas, uma que especifica as informações de solicitação necessárias para usar a API de back-end (API Geocoding do Google) e a segunda que realmente envia a solicitação para a API de back-end. Em seguida, vamos processar a resposta.

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

Os principais elementos da política ExtractVariable são:

• <ExtractVariables name> : novamente, o nome da política é usado para se referir à política quando ela é usada em um fluxo.
• <Source> : especifica a variável de resposta que criamos na política ServiceCallout. Essa é a variável da qual essa política extrai dados.
• <VariablePrefix> : o prefixo da variável especifica um namespace para outras variáveis criadas nessa política. O prefixo pode ser qualquer nome, exceto os nomes reservados definidos pelas variáveis predefinidas do Edge.
• <JSONPayload> : esse elemento recupera os dados de resposta que nos interessam e os coloca em variáveis nomeadas. Na verdade, a API Geocoding retorna muito mais informações do que latitude e longitude. No entanto, esses são os únicos valores de que precisamos para este exemplo. Você pode conferir uma renderização completa do JSON retornado pela API Geocoding na documentação da API. Os valores de geometry.location.lat e geometry.location.lng são simplesmente dois dos muitos campos no objeto JSON retornado.

Pode não ser óbvio, mas é importante observar que ExtractVariables produz duas variáveis cujos nomes consistem no prefixo da variável (geocoderesponse) e nos nomes de variáveis reais especificados na política. Essas variáveis são armazenadas no proxy de API e estarão disponíveis para outras políticas no fluxo de proxy, como você verá. As variáveis são:

• geocoderesponse.latitude
• geocoderesponse.longitude

A maior parte do trabalho já foi feita. Criamos um composto de três políticas que formam uma solicitação, chamam uma API de back-end e analisam os dados JSON retornados. Nas etapas finais, vamos inserir dados dessa parte do fluxo em outra política AssignMessage, chamar a segunda API de back-end (API Google Elevation) e retornar nossos dados combinados ao desenvolvedor de apps.

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

Se você examinar a API Google Elevation, verá que ela usa dois parâmetros de consulta. O primeiro é chamado de locations e o valor dele é a latitude e a longitude (valores separados por vírgula). O outro parâmetro é sensor, que é obrigatório e precisa ser verdadeiro ou falso. O mais importante a observar neste momento é que a mensagem de solicitação que criamos aqui não exige uma ServiceCallout. Não precisamos chamar a segunda API de uma ServiceCallout neste momento porque podemos chamar a API de back-end do TargetEndpoint do proxy. Se você pensar bem, temos todos os dados necessários para chamar a API Google Elevations A mensagem de solicitação gerada nesta etapa não exige uma ServiceCallout, assim como a solicitação gerada para o pipeline de solicitação principal, e, portanto, será simplesmente encaminhada pelo ProxyEndpoint para o TargetEndpoint, seguindo a RouteRule configurada para esse proxy de API. O TargetEndpoint gerencia a conexão com a API remota. Lembre-se de que o URL da API Elevation é definido no HTTPConnection para o TargetEndpoint. Documentação da API Elevation se você quiser saber mais. Os QueryParams que armazenamos anteriormente, country e postalcode, não são mais necessários. Portanto, os removemos aqui.

Breve pausa: voltar ao fluxo

Neste momento, você pode se perguntar por que não estamos criando outra política ServiceCallout. Afinal, criamos outra mensagem. Como essa mensagem é enviada para o destino, a API Google Elevation? A resposta está no elemento <RouteRule> do fluxo. <RouteRule> especifica o que fazer com as mensagens de solicitação restantes depois que a parte <Request> do fluxo for executada. O TargetEndpoint especificado por essa <RouteRule> informa ao proxy de API para entregar a mensagem a http://maps.googleapis.com/maps/api/elevation/xml.

Se você fez o download do proxy de API de amostra, poderá encontrar o XML do TargetProxy no arquivo 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>

Agora, só precisamos processar a resposta da API Google Elevation e pronto.

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

A resposta inclui o local geocodificado para o centro do código postal fornecido por o usuário final do app, combinado com a elevação nesse local geocodificado. Os dados foram recuperados de duas APIs de back-end, combinados com políticas anexadas ao proxy de API e retornados ao cliente em uma única resposta.

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

Resumo

Este tópico do manual explicou como usar o padrão de composição de políticas para criar um mashup de dados de várias fontes de back-end. A composição de políticas é um padrão comum usado no desenvolvimento de proxy de API para adicionar funcionalidades criativas à API.