Como programar proxies de API com JavaScript

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Neste tópico, você vai aprender a usar JavaScript para adicionar cabeçalhos HTTP dinamicamente a uma mensagem de resposta e como analisar uma resposta JSON e retornar um subconjunto de propriedades ao app solicitante.

Fazer o download e testar o exemplo de código

Sobre este exemplo de livro de receitas

Este exemplo de livro de receitas ilustra um padrão de proxy de API em que o comportamento da API é implementado no JavaScript. Os exemplos de JavaScript foram criados para mostrar como trabalhar com variáveis simples e conteúdo de mensagens. Uma amostra mostra como receber variáveis get e set. O segundo exemplo mostra como analisar o JSON e criar uma mensagem com base no resultado.

Há dois exemplos de JavaScript no proxy de API:

  • setHeaders.js: este JavaScript recebe os valores de algumas variáveis definidas quando um proxy de API é invocado. O JavaScript adiciona essas variáveis à mensagem de resposta para que você possa conferir os valores delas para cada solicitação feita.
  • minimize.js: este JavaScript mostra como trabalhar com o conteúdo da mensagem. A ideia por trás desta amostra é que um serviço geralmente retorna mais dados do que o necessário. Assim, o JavaScript analisa a mensagem de resposta, extrai algumas propriedades interessantes e as usa para criar o conteúdo da mensagem de resposta.

Código para setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Código para minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

É possível acessar as variáveis de fluxo em JavaScript por meio do objeto de contexto. Esse objeto faz parte do modelo de objetos do Edge JavaScript. Para detalhes sobre o modelo de objeto, consulte Modelo de objeto JavaScript.

Antes de começar

Antes de ver este exemplo do livro de receitas, conheça estes conceitos fundamentais:

  • O que são políticas e como anexá-las a proxies. Para uma boa introdução a políticas, consulte O que é uma política?.
  • A estrutura de um fluxo de proxy, conforme explicado em Como configurar fluxos. Os fluxos permitem especificar a sequência em que as políticas são executadas por um proxy de API. Neste exemplo, várias políticas são criadas e adicionadas a um fluxo de proxy da API.
  • Como um projeto de proxy de API é organizado no seu sistema de arquivos, conforme explicado na Referência de configuração de proxy de API.
  • Conhecimento prático sobre XML, JSON e JavaScript. Neste exemplo, você cria o proxy de API e as políticas dele com arquivos XML que residem no sistema de arquivos.

Se você fez o download do exemplo de código, pode localizar todos os arquivos discutidos neste tópico na pasta de exemplo javascript-cookbook. As seções a seguir abordam o exemplo de código em detalhes.

Noções básicas sobre o fluxo do proxy

Para que o JavaScript seja executado em um proxy de API, é necessário anexá-lo a um fluxo usando um anexo de política chamado de "Etapa". Uma política do tipo JavaScript (com as letras maiúsculas e minúsculas) simplesmente contém uma referência ao nome de um arquivo JavaScript. Aponte a política para um arquivo JavaScript usando o elemento ResourceURL.

Por exemplo, a política a seguir faz referência ao arquivo JavaScript chamado setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Você pode anexar essa política a um fluxo de proxy de API como faria com qualquer outro tipo de política. Ao anexar a política ao fluxo de proxy da API, você indica onde o JavaScript precisa ser executado. Isso permite que você execute um JavaScript que interage com mensagens de solicitação ou de resposta enquanto essas mensagens "fluem" pelo proxy de API. Neste exemplo, os dois JavaScripts são executados no fluxo de resposta, já que as políticas fazem duas coisas: definir cabeçalhos HTTP na mensagem de resposta e "minimizar" a mensagem de resposta que o Apigee Edge retorna ao aplicativo solicitante.

Se você abrir essa configuração de fluxo na interface de gerenciamento, verá a configuração do fluxo abaixo.

Selecione Proxy Endpoints > default > PostFlow no Painel do navegador.

A configuração XML correspondente para o ProxyEndpoint chamada "padrão" é mostrada abaixo.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Veja um resumo dos elementos do fluxo.

  • <Request>: o elemento <Request> consiste em vários elementos <Step>. Cada etapa chama uma das políticas que você cria no restante deste tópico. Essas políticas anexam um JavaScript ao fluxo de proxy de API, e o local do anexo da política determina quando o JavaScript é executado.
  • <Response>: o elemento <Response> também inclui <Steps>. Essas etapas também chamam as políticas responsáveis pelo processamento da resposta final do destino (que neste exemplo é o destino de serviço simulado da Apigee. Observe a configuração HTTPTargetConnection em /apiproxy/targets/default.xml.)
  • <HTTPProxyConnection>: especifica o caminho do host e do URI que define o endereço de rede que os apps chamam para consumir essa API.
  • <RouteRule>: este elemento especifica qual configuração de TargetEndpoint é invocada pelo ProxyEndpoint.

Como adicionar código JavaScript a um proxy

O JavaScript (como scripts Python, arquivos JAR Java, arquivos DEX e assim por diante) são armazenados como recursos. Quando você está começando a trabalhar com JavaScript, é mais fácil armazenar seus arquivos JavaScript no proxy de API. À medida que você avança, o JavaScript precisa ser o mais genérico e reutilizável possível e, em seguida, armazenado no nível do ambiente ou da organização. Isso evita a necessidade de armazenar os mesmos arquivos JavaScript em vários proxies de API, o que pode rapidamente se tornar impossível de gerenciar.

Para saber como armazenar recursos no nível da organização e do ambiente, consulte Arquivos de recursos.

Testar

Para instruções sobre como implantar e chamar o proxy, consulte o README do manual do JavaScript (em inglês).

Como importar e implantar o proxy de API

Depois de fazer as mudanças, salve o proxy de API na ferramenta Criador de proxy de API, na interface de gerenciamento.

Ou execute o seguinte comando no diretório /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Como testar o JavaScript

Execute o seguinte comando no diretório /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

A sinalização de curl -v é usada no script de shell para visualizar cabeçalhos HTTP na mensagem de resposta modificada pelo JavaScript.

É possível enviar uma solicitação diretamente da seguinte forma:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 

Se o JavaScript for executado corretamente, você verá uma resposta como esta:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Agora é possível modificar o JavaScript para tentar coisas novas, reimplantar o proxy de API e verificar os resultados enviando a mesma solicitação. Sempre implante o proxy de API que contém o JavaScript para que as alterações entrem em vigor.

Erros de script

É inevitável encontrar erros ao escrever em JavaScript. Confira abaixo o formato dos erros de JavaScript emitidos por um proxy de API.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Quando usar JavaScript

No Apigee Edge, geralmente há mais de uma maneira de implementar funcionalidades específicas. Use políticas prontas quando possível e evite a tentação de codificar toda a lógica de proxy da API em JavaScript. Mesmo que o Apigee Edge aproveite o JavaScript compilado para melhorar o desempenho, é improvável que o JavaScript tenha um desempenho tão bom quanto o de políticas. O JavaScript pode ser mais difícil de manter e depurar. Reserve o JavaScript para uma funcionalidade exclusiva para seus requisitos.

Se o desempenho for uma preocupação para a funcionalidade personalizada, use Java sempre que possível.

Resumo

Neste tópico do manual, você aprendeu como o JavaScript pode ser incluído em uma configuração de proxy de API para implementar um comportamento personalizado. O comportamento personalizado implementado pelas amostras demonstra como receber as variáveis, além de analisar o JSON e criar mensagens de resposta personalizadas.