O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Como programar proxies de API com JavaScript

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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

Fazer o download e testar o exemplo de código

Sobre este exemplo de manual

Este exemplo de manual ilustra um padrão de proxy de API em que você implementa o comportamento da API em JavaScript. Os exemplos de JavaScript foram projetados para mostrar como trabalhar com variáveis simples e conteúdo de mensagens. Um exemplo mostra como receber e definir variáveis. O segundo exemplo mostra como analisar JSON e construir uma mensagem a partir do resultado.

Dois exemplos de JavaScript estão 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 conferir os valores delas para cada solicitação feita.
minimize.js: esse JavaScript mostra como trabalhar com o conteúdo da mensagem. A ideia por trás desse exemplo é que um serviço geralmente retorna mais dados do que é necessário. Portanto, o JavaScript analisa a mensagem de resposta, extrai algumas propriedades interessantes propriedades e as usa para criar o conteúdo da mensagem de resposta.

O código de 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 de 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 pelo objeto de contexto. Esse objeto faz parte do modelo de objeto JavaScript do Edge. Para mais detalhes sobre o modelo de objeto, consulte Modelo de objeto JavaScript.

Antes de começar

Antes de explorar este exemplo de manual, 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 às 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 sistema de arquivos, conforme explicado em Referência de configuração de proxy de API.
Um conhecimento prático de 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, poderá encontrar todos os arquivos discutidos neste tópico na pasta de exemplo javascript-cookbook. As seções a seguir discutem o exemplo de código em detalhes.

Noções básicas sobre o fluxo de 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 "etapa". Uma política do tipo JavaScript (observe a capitalização) contém apenas 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>

Prática recomendada: sempre use a extensão .js para recursos JavaScript.

É possível 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 precisa ser executado. Isso permite executar o JavaScript que interage com mensagens de solicitação ou mensagens de 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 app solicitante.

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

Selecione Endpoints de proxy > padrão > PostFlow no painel Navigator.

A configuração XML correspondente para o ProxyEndpoint chamado "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>

Confira um resumo dos elementos do fluxo.

<Request> : o elemento <Request> consiste em vários <Step> elementos. Cada etapa chama uma das políticas criadas 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 políticas responsáveis por processar a resposta final do destino (que, neste exemplo, é o destino de serviço simulado do Apigee. Observe a configuração HTTPTargetConnection em /apiproxy/targets/default.xml.)
<HTTPProxyConnection> : especifica o host e o caminho 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.

Adicionar código JavaScript a um proxy

O JavaScript (como scripts Python, arquivos JAR Java, arquivos XSLT e assim por diante) é armazenado 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 o mais genérico e reutilizável possível e, em seguida, armazenado no nível do ambiente ou da organização. Isso evita que você precise armazenar os mesmos arquivos JavaScript em vários proxies de API, o que pode se tornar rapidamente incontrolável.

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

Faça um teste

Para instruções sobre como implantar e chamar o proxy, consulte o README do manual do JavaScript.

Importar e implantar o proxy de API

Depois de fazer as mudanças, você pode salvar o proxy de API na ferramenta de criação de proxy de API na interface de gerenciamento.

Ou você pode executar o seguinte comando no diretório /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Testar o JavaScript

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

$ sh invoke.sh

O flag da curl -v é usado no script de shell para conferir os cabeçalhos HTTP na mensagem de resposta modificada pelo JavaScript.

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

$ 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 você pode modificar o JavaScript para tentar novas ações, 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 mudanças entrem em vigor.

Erros de script

Você inevitavelmente verá erros ao escrever JavaScript. O formato dos erros de JavaScript que serão emitidos 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 o JavaScript

No Apigee Edge, geralmente há mais de uma maneira de implementar funcionalidades específicas. Use políticas prontas sempre que possível e evite a tentação de codificar toda a lógica do proxy de API em JavaScript. Embora o Apigee Edge aproveite o JavaScript compilado para melhorar a performance, é improvável que o JavaScript funcione tão bem quanto as políticas. O JavaScript pode ser mais difícil de manter e depurar. Reserve o JavaScript para funcionalidades exclusivas dos seus requisitos.

Se a performance for uma preocupação para funcionalidades personalizadas, use o 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 pelos exemplos demonstra como receber e variáveis e como analisar JSON e construir mensagens de resposta personalizadas.