Proxies de API de programação com JavaScript

Você está vendo a documentação do Apigee Edge.
Consulte a documentação do Apigee X.

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

Faça o download e teste o código de amostra

Sobre este exemplo de livro de receitas

Este exemplo de livro de receitas ilustra um padrão de proxy de API em que você implementa o comportamento da API em JavaScript. Os exemplos em JavaScript foram desenvolvidos para mostrar como trabalhar com variáveis simples e conteúdo de mensagem. Um exemplo mostra como usar as variáveis get e set. O segundo exemplo mostra como analisar o JSON e criar uma mensagem a partir do resultado.

Há dois exemplos de JavaScript no proxy de API:

  • setHeaders.js: esse JavaScript recebe os valores de algumas variáveis que são definidas quando um proxy de API é invocado. O JavaScript adiciona essas variáveis à mensagem de resposta para que você possa ver os valores de cada solicitação feita.
  • minimize.js: esse JavaScript mostra como trabalhar com conteúdo de mensagens. A ideia por trás dessa 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.

O 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"));

O 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 variáveis de fluxo em JavaScript por meio do objeto de contexto. Esse objeto faz parte do modelo de objeto JavaScript do Edge. Para detalhes sobre o modelo de objeto, consulte Modelo de objeto JavaScript.

Antes de começar

Antes de explorar este exemplo de livro de receitas, você também precisa conhecer estes conceitos fundamentais:

  • O que são políticas e como anexá-las a proxies. Para uma boa introdução sobre as 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 de API.
  • Como um projeto de proxy de API é organizado no seu sistema de arquivos, conforme explicado na Referência de configuração do proxy de API.
  • Experiência em trabalhar com XML, JSON e JavaScript. Neste exemplo, você cria o proxy de API e as respectivas políticas com arquivos XML que residem no sistema de arquivos.

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

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

Para executar o JavaScript em um proxy de API, é preciso anexá-lo a um fluxo usando um anexo de política chamado de "Etapa". Uma política do tipo JavaScript (a capitalização de notas) simplesmente contém uma referência ao nome de um arquivo JavaScript. Você aponta 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 de API, você indica onde o JavaScript será executado. Isso permite que você execute o JavaScript que interage com as mensagens de solicitação ou resposta à medida que 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 IU de gerenciamento, verá a configuração de fluxo abaixo.

Selecione Proxy Endpoints > default > PostFlow no painel 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 criadas ao longo deste tópico. Essas políticas anexam um JavaScript ao fluxo de proxy de API, e o local do anexo de política determina quando o JavaScript é executado.
  • <Response> - O elemento <Response> também inclui <Steps>. Essas etapas também chamam políticas responsáveis pelo processamento da resposta final do destino, que neste exemplo é a simulação de destino de serviço da Apigee. Observe a configuração HTTPTargetConnection em /apiproxy/targets/default.xml.
  • <HTTPProxyConnection>: especifica o caminho do host e do URI que definem o endereço de rede que os apps chamam para consumir essa API.
  • <RouteRule>: esse elemento especifica qual configuração de TargetEndpoint é invocada pelo ProxyEndpoint.

Como adicionar código JavaScript a um proxy

JavaScript (como scripts Python, arquivos JAR do Java, arquivos XSLT e assim por diante) são armazenados como recursos. Quando você está começando a trabalhar com JavaScript, é mais fácil armazenar os arquivos JavaScript no proxy de API. À medida que você avança, o JavaScript precisa ser tornado 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 incontrolável.

Para saber mais sobre 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 alterações, é possível Salvar o proxy de API na ferramenta Criador de proxy de API na IU de gerenciamento.

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

$ sh deploy.sh

Como testar JavaScript

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

$ sh invoke.sh

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

Você pode 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 da 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

Inevitavelmente, você verá erros ao escrever em JavaScript. O formato de erros de JavaScript que você verá emitido por um proxy de API é mostrado abaixo.

{  
   "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 para uso sempre que possível e evite a tentação de codificar toda a lógica de proxy de API em JavaScript. Embora o Apigee Edge use o JavaScript compilado para melhorar o desempenho, é improvável que o JavaScript tenha um desempenho tão bom quanto nas políticas. Pode ser mais difícil manter e depurar o JavaScript. Reserve o JavaScript para ter uma funcionalidade exclusiva para suas necessidades.

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

Resumo

Neste tópico do livro de receitas, você aprendeu como o JavaScript pode ser incluído na configuração de um proxy de API para implementar o comportamento personalizado. O comportamento personalizado implementado pelas amostras demonstra como obter variáveis e como analisar JSON e construir mensagens de resposta personalizadas.