Esta página foi traduzida pela API Cloud Translation.

Como programar proxies de API com JavaScript

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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

Fazer o download e testar o exemplo de código

Sobre este exemplo de livro de receitas

Este exemplo do manual ilustra um padrão de proxy de API no qual você implementa o comportamento da API em JavaScript. Os exemplos de JavaScript foram criados para mostrar como trabalhar com variáveis simples e o conteúdo das mensagens. Um exemplo mostra como get e set. A segunda mostra como analisar o JSON e criar 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 à resposta para que você possa ver os valores de cada solicitação que fizer.
minimize.js: esse JavaScript mostra como trabalhar com mensagens conteúdo. A ideia por trás dessa amostra é que um serviço muitas vezes retorna mais dados do que necessários. Assim, o JavaScript analisa a mensagem de resposta, extrai alguns dados 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. Este objeto faz parte de modelo de objeto do Edge JavaScript. Para mais detalhes sobre o modelo de objetos, consulte Modelo de objeto JavaScript.

Antes de começar

Antes de explorar este exemplo do livro de receitas, você também deve se familiarizar com estes conceitos conceitos importantes:

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

Se você fez download do exemplo de código, poderá localizar todos os arquivos discutidos nesta 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 de proxy

Para que o JavaScript seja executado em um proxy de API, é necessário anexá-lo a um fluxo usando uma política anexo chamado "Etapa". Uma política do tipo JavaScript (letras maiúsculas de observação) contém simplesmente 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 qualquer outro tipo de política. De anexar a política ao fluxo do proxy da API, você indica onde o JavaScript deve ser executado. Isso permite executar um JavaScript que interage com mensagens de solicitação ou de resposta já que o "fluxo" dessas mensagens por meio do proxy de API. Neste exemplo, ambos os JavaScripts são executados na fluxo de resposta, já que as políticas fazem duas coisas: definem 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, vai encontrar a configuração a seguir.

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

A configuração XML correspondente para o ProxyEndpoint chamada "default" é mostrado a seguir.

<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>: a <Request> de um elemento consiste em várias <Step> os elementos. Cada etapa chama uma das políticas criadas por meio do restante sobre este assunto. Essas políticas anexam um JavaScript ao fluxo de proxy da API e o local anexo de política determina quando o JavaScript é executado.
<Response>: o campo <Response> também inclui <Etapas>. Essas etapas também chamam as políticas responsáveis pelo processamento do alvo (que neste exemplo é o destino de serviço simulado da Apigee). Observe o HTTPTargetConnection em /apiproxy/targets/default.xml.
<HTTPProxyConnection>: especifica o caminho do host e do URI que defina o endereço de rede que os apps chamam para consumir essa API.
<RouteRule>: este elemento especifica qual TargetEndpoint é invocada pelo ProxyEndpoint.

Adicionar código JavaScript a um proxy

O JavaScript (como scripts Python, arquivos Java JAR, arquivos WebGL e assim por diante) é armazenado como recursos. Quando estiver começando a trabalhar com JavaScript, é mais fácil armazenar seu JavaScript no proxy da API. À medida que você avança, o JavaScript deve ser genérico e reutilizáveis e armazenados no nível do ambiente ou da organização. Isso evita que você tenha que armazenar os mesmos arquivos JavaScript em vários proxies de API, o que pode rapidamente se tornar 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 obter instruções sobre como implantar e chamar o proxy, consulte a README do manual em JavaScript.

Como importar e implantar o proxy de API

Depois de fazer as mudanças, você pode Salvar o proxy de API no criador 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

Como testar JavaScript

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

$ sh invoke.sh

A flag curl -v é usada no script de shell para conferir cabeçalhos HTTP na resposta modificada pelo JavaScript.

Você pode 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 é possível modificar o JavaScript para testar coisas novas, reimplantar o proxy de API e verificar e enviar a mesma solicitação. Sempre implante o proxy de API que contém seu JavaScript para que as alterações entrem em vigor.

Erros de script

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

Na Apigee Edge, geralmente há mais de uma maneira de implementar uma funcionalidade específica. Usar sempre que possível, e evite a tentação de codificar todo o proxy de API. lógica em JavaScript. Embora o Apigee Edge aproveite o JavaScript compilado para melhorar desempenho, é improvável que o JavaScript tenha um desempenho tão bom quanto o das Políticas. O JavaScript pode ser mais difíceis de manter e depurar. Reserve o JavaScript para funcionalidades exclusivas da sua e cumprimento de requisitos regulatórios.

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

Resumo

Neste tópico do manual, você aprendeu como o JavaScript pode ser incluído em um proxy de API para implementar o comportamento personalizado. O comportamento personalizado implementado pelas amostras demonstrar como obter variáveis e e como analisar JSON e criar mensagens.