Política de JavaScript

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O que

Essa política permite adicionar um código JavaScript personalizado que é executado no contexto de um fluxo de proxy de API. No seu código JavaScript personalizado, é possível usar os objetos, métodos e propriedades do modelo de objeto JavaScript da Apigee. O modelo de objeto permite obter, definir e remover variáveis no contexto do fluxo de proxy. Também é possível usar funções criptográficas básicas fornecidas com o modelo de objeto.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Sobre

Há muitos casos de uso da política do JavaScript. Por exemplo, é possível receber e definir variáveis de fluxo, executar a lógica personalizada e executar o processamento de falhas, além de extrair dados de solicitações ou respostas, editar dinamicamente o URL de destino do back-end e muito mais. Essa política permite que você implemente um comportamento personalizado que não é coberto por nenhuma outra política padrão da Apigee. Na verdade, você pode usar uma política JavaScript para atingir muitos dos mesmos comportamentos implementados por outras políticas, como o AssignMessage e o ExtractVariable.

Um caso de uso que não recomendamos para a política JavaScript é o registro. A política MessageLogging é muito mais adequada para geração de registros em plataformas de registro de terceiros, como Splunk, Sumo e Loggly. Você melhora o desempenho do proxy de API executando a política MessageLogging no PostClientFlow, que é executada depois que a resposta é enviada de volta ao cliente.

A política do JavaScript permite especificar um arquivo de origem do JavaScript a ser executado ou incluir o código do JavaScript diretamente na configuração da política com o elemento <Source>. De qualquer forma, o código do JavaScript será executado quando a etapa a que a política está anexada for executada. Para a opção de arquivo de origem, o código-fonte é sempre armazenado em um local padrão no pacote do proxy: apiproxy/resources/jsc. Se preferir, armazene o código-fonte em um arquivo de recurso no nível do ambiente ou da organização. Para instruções, consulte Arquivos de recursos. Também é possível fazer o upload do JavaScript por meio do editor de proxy da IU da Apigee.

Os arquivos de origem JavaScript sempre precisam ter uma extensão .js.

A Apigee é compatível com JavaScript executado no mecanismo JavaScript Rhino 1.7.13.

Vídeo

Observação: o vídeo a seguir mostra o editor clássico de proxy na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada no vídeo.

Assista a um breve vídeo para saber como criar uma extensão de política personalizada usando a política JavaScript.

Amostras

Reescrever o URL de destino

Veja um caso de uso comum: como extrair dados de um corpo de solicitação, armazená-los em uma variável de fluxo e usar essa variável de fluxo em outro lugar do fluxo de proxy. Digamos que você tenha um aplicativo onde o usuário insere o nome em um formulário HTML e o envia. Você quer que o proxy de API extraia os dados do formulário e os adicione dinamicamente ao URL usado para chamar o serviço de back-end. Como você faria isso em uma política JavsScript?

Observação: se você quiser testar este exemplo, suponha que você tenha criado um novo proxy no editor de proxy. Ao criá-lo, basta dar a ele um URL de serviço de back-end: http://www.example.com. Neste exemplo, vamos reescrever o URL do back-end dinamicamente. Se você não sabe como criar um novo proxy, consulte o tutorial de primeiros passos.

1. Na IU da Apigee, abra o proxy que você criou no editor de proxy.
2. Selecione a guia Desenvolver.
3. No menu "Novo", selecione Novo script.
4. Na caixa de diálogo, selecione JavaScript e atribua um nome ao script, como js-example.
5. Cole o código a seguir no editor de código e salve o proxy. O importante é observar o objeto context. Esse objeto está disponível para o código JavaScript em qualquer lugar no fluxo do proxy. É usado para receber constantes específicas do fluxo, chamar métodos get/set úteis e realizar mais operações. Esta parte de objeto é do modelo de objeto JavaScript da Apigee. Observe também que a variável de fluxo target.url é uma variável integrada de leitura/gravação que pode ser acessada no fluxo de solicitação de destino. Quando definimos essa variável com o URL da API, a Apigee faz a chamada de back-end para esse URL. Basicamente, reescrevemos o URL de destino original, que era o que você especificou ao criar o proxy (por exemplo, http://www.example.com
   
   

   if (context.flow=="PROXY_REQ_FLOW") {
        var username = context.getVariable("request.formparam.user");
        context.setVariable("info.username", username);
   }
   
   
   if (context.flow=="TARGET_REQ_FLOW") {
        context.setVariable("request.verb", "GET");
        var name = context.getVariable("info.username");
        var url = "http://mocktarget.apigee.net/"
        context.setVariable("target.url", url + "?user=" + name);
   }
6. No menu "Nova política", selecione JavaScript.
7. Dê um nome à política, como target-rewrite. Aceite os padrões e salve a política.
8. Se você selecionar o pré-fluxo do endpoint do proxy no Navegador, verá que a política foi adicionada a esse fluxo.
9. No Navegador, selecione o ícone pré-fluxo do endpoint de destino.
10. No Navegador, arraste a política JavaScript para o lado da solicitação do endpoint de destino no editor de fluxo.
11. Salvar.
12. Chame a API da seguinte maneira, substituindo o nome da organização e o proxy corretos conforme apropriado:

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Por fim, vejamos a definição de XML para a política JavaScript usada neste exemplo. É importante observar que o elemento <ResourceURL> é usado para especificar o arquivo de origem JavaScript a ser executado. Esse mesmo padrão é usado para qualquer arquivo com origem JavaScript: jsc://filename.js. Se o código JavaScript exigir inclusões, use um ou mais elementos <IncludeURL> para isso, conforme descrito mais adiante nesta referência.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

Recuperar valor de propriedade do JavaScript

É possível adicionar um elemento <Property> na configuração e recuperar o valor do elemento com JavaScript no ambiente de execução.

Use o atributo name do elemento para especificar o nome com que acessar a propriedade a partir do código JavaScript. O valor do elemento <Property> (o valor entre as tags de abertura e fechamento) é o valor literal que será recebido pelo JavaScript.

Em JavaScript, você recupera o valor da propriedade da política acessando-o como uma propriedade do objeto Properties, como no seguinte:

• Configure a propriedade Aqui, o valor da propriedade é o nome da variável response.status.code.

  <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite">
      <DisplayName>JavascriptURLRewrite</DisplayName>
      <Properties>
          <Property name="source">response.status.code</Property>
      </Properties>
      <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL>
  </Javascript>

• Recupere a propriedade com JavaScript. Aqui, o valor recuperado, um nome de variável, é usado pela função getVariable para recuperar o valor da variável.

  var responseCode = properties.source; // Returns "response.status.code"
  var value = context.getVariable(responseCode); // Get the value of response.status.code
  context.setVariable("response.header.x-target-response-code", value);

Como processar os erros

Para exemplos e uma discussão sobre técnicas de tratamento de erros que podem ser usadas em uma chamada de JavaScript, consulte Forma correta para retornar erro da política JavaScript. As sugestões oferecidas na comunidade da Apigee são apenas para fins informativos e não representam necessariamente as práticas recomendadas pelo Google.

Em uma política do JavaScript, o acesso a request.content.asJSON em uma capacidade somente leitura faz com que números inteiros grandes sejam convertidos em notação exponencial no corpo da mensagem. Como resultado, a mensagem será substituída pelos valores convertidos.

---

Referência de elemento

A referência de elementos descreve os elementos e atributos da política do JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" 
        continueOnError="false" enabled="true" timeLimit="200" 
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>
</Javascript>

Atributos <JavaScript>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Os atributos a seguir são específicos dessa política.

Atributo	Descrição	Padrão	Presence
timeLimit	Especifica o tempo máximo (em milissegundos) que o script pode executar. Por exemplo, se um limite de 200 ms for excedido, a política vai gerar o erro: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. Observação: para contas de avaliação gratuita, o tempo de execução é limitado a 200 ms.	N/A	Obrigatório

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <IncludeURL>

Especifica um arquivo da biblioteca do JavaScript que será carregado como dependência ao arquivo do JavaScript principal especificado com o elemento <ResourceURL> ou <Source>. Os scripts serão avaliados na ordem em que estão listados na política. O código pode usar os objetos, métodos e propriedades do modelo de objeto JavaScript.

Inclua mais de um recurso de dependência JavaScript com elementos <IncludeURL> adicionais.

Aviso: se os arquivos JavaScript estiverem armazenados no nível da organização ou do ambiente, verifique se eles foram enviados corretamente com cURL usando a opção -F ou como um arquivo anexado por meio de um cliente REST. O Content-Type é multipart/form-data. Para mais informações, consulte Como gerenciar recursos.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Padrão:	Nenhum
Presença:	Opcional
Tipo:	String

Exemplo

Veja o exemplo básico na seção Amostras.

Elemento <Property>

Especifica uma propriedade que você pode acessar a partir do código JavaScript no momento da execução.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Padrão:	Nenhum
Presença:	Opcional
Tipo:	String

Atributos

Atributo	Descrição	Padrão	Presence
nome	Especifica o nome da propriedade.	N/A	Obrigatório.

Exemplo

Veja o exemplo na seção Amostras.

Elemento <ResourceURL>

Especifica o arquivo JavaScript principal que será executado no fluxo da API. É possível armazenar esse arquivo no escopo do proxy de API (em /apiproxy/resources/jsc no pacote de proxy de API ou na seção "Scripts" do painel do Navegador do editor de proxy de API) ou na organização ou escopos de ambiente para reutilização em vários proxies de API, conforme descrito em Como gerenciar recursos. O código pode usar os objetos, métodos e propriedades do modelo de objeto JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Padrão:	Nenhum
Presença:	É necessário <ResourceURL> ou <Source>. Se <ResourceURL> e <Source> estiverem presentes, <ResourceURL> será ignorado.
Tipo:	String

Exemplo

Veja o exemplo básico na seção Amostras.

Elemento <Source>

Permite inserir o JavaScript diretamente na configuração XML da política. O código do JavaScript inserido será executado quando a política for executada no fluxo da API.

Padrão:	Nenhum
Presença:	É necessário <ResourceURL> ou <Source>. Se <ResourceURL> e <Source> estiverem presentes, <ResourceURL> será ignorado.
Tipo:	String

Exemplo

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

Elemento <SSLInfo>

Especifica as propriedades usadas para configurar o TLS para todas as instâncias do cliente HTTP criadas pela política JavaScript.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Padrão:	Nenhum
Presença:	Opcional
Tipo:	String

O processo de configuração do TLS para um cliente HTTP é o mesmo que você usa para configurar o TLS para um TargetEndpoint/TargetServer. Saiba mais em Opções para configurar o TLS.

Observações sobre uso

Aviso: as chamadas do sistema não são permitidas pelo modelo de segurança. Por exemplo: o sistema de arquivos interno lê e grava, além de receber informações atuais do usuário, a lista de processos ou o uso da CPU/memória. Embora algumas chamadas possam ser funcionais, elas não são compatíveis e responsáveis para serem suspensas a qualquer momento. Para compatibilidade com versões futuras, evite fazer essas chamadas no seu código.

Como depurar o código da política JavaScript

Use a função print() para enviar informações de depuração para o painel de saída da transação na ferramenta Debug. Para detalhes e exemplos, consulte Debug com instruções print() do JavaScript.

Para ver as declarações de impressão em Debug:

1. Abra a ferramenta Debug e inicie uma sessão de trace para um proxy que contenha a política do JavaScript.
2. Chame o proxy.
3. Na Ferramenta Debug, clique em Saída de todas as transações para abrir o painel de saída.

   

4. Suas declarações de impressão aparecerão neste painel.

Use a função print() para gerar informações de depuração na ferramenta de depuração. Essa função está disponível diretamente por meio do modelo de objeto JavaScript. Para mais detalhes, consulte Depure o JavaScript com instruções print().

Variáveis de fluxo

Essa política não preenche nenhuma variável por padrão. No entanto, você pode definir (e receber) variáveis de fluxo no código JavaScript chamando métodos no objeto de contexto. Um padrão típico é assim:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

O objeto de contexto faz parte do modelo de objeto JavaScript da Apigee.

Referência de erros

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. É importante conhecer estas informações se estiver a desenvolver regras de falhas para resolver falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Código de falha	Estado de HTTP	Causa	Corrigir
steps.javascript.ScriptExecutionFailed	500	A política de JavaScript pode gerar muitos tipos diferentes de erros de ScriptExecutionFailed. Os tipos de erros mais comuns incluem: RangeError, ReferenceError, SyntaxError, TypeError e URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Ocorreu um erro no código JavaScript. Consulte a string de falha para ver detalhes.	N/A
steps.javascript.ScriptSecurityError	500	Ocorreu um erro de segurança quando o JavaScript foi executado. Consulte a string de falha para ver detalhes.	N/A

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Sugestão: precisa de ajuda para resolver um erro? Clique em junto à descrição da causa do erro para visitar a página de resolução de problemas.

Nome do erro	Causa	Corrigir
InvalidResourceUrlFormat	Se o formato do URL do recurso especificado no elemento <ResourceURL> ou <IncludeURL> da política JavaScript for inválido, a implementação do proxy de API falha.
InvalidResourceUrlReference	Se os elementos <ResourceURL> ou <IncludeURL> fizerem referência a um ficheiro JavaScript que não existe, a implementação do proxy de API falha. O ficheiro de origem referenciado tem de existir ao nível do proxy de API, do ambiente ou da organização.
WrongResourceType	Este erro ocorre durante a implementação se os elementos <ResourceURL> ou <IncludeURL> da política JavaScript fizerem referência a qualquer tipo de recurso que não seja jsc (ficheiro JavaScript).
NoResourceURLOrSource	A implementação da política JavaScript pode falhar com este erro se o elemento <ResourceURL> não for declarado ou se o URL do recurso não for definido neste elemento. O elemento <ResourceURL> é um elemento obrigatório. Ou, o elemento <IncludeURL> é declarado, mas o URL do recurso não está definido neste elemento. O elemento <IncludeURL> é opcional, mas, se for declarado, o URL do recurso tem de ser especificado no elemento <IncludeURL>.

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro no tempo de execução. Para mais informações, consulte o artigo O que precisa de saber sobre os erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	javascript.JavaScript-1.failed = true

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque pode mudar.

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Exemplo de regra de falha

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

Esquema

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.

Temas relacionados

• Modelo de objeto JavaScript

Artigos da comunidade Apigee

Consulte os seguintes artigos relacionados na Comunidade da Apigee:

• Como lidar com cabeçalhos de múltiplos valores em JavaScript?