Política de JavaScript

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

O que

Essa política permite adicionar um código JavaScript personalizado que é executado no contexto de um fluxo de proxy de API. No código JavaScript personalizado, você pode usar os objetos, métodos e propriedades de o modelo de objeto JavaScript do Apigee Edge. 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.

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ê implementar um comportamento personalizado que não seja coberto por nenhuma outra política padrão do Edge. 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 de geração de registros de mensagens é 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 da API executando a política de geração de registros de mensagens 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.

Consulte Software e versões compatíveis (em inglês) para a versão do JavaScript compatível no momento.

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

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

<?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>

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.

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

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.

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

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>

Atributos

Exemplo

Veja o exemplo na seção Amostras.

Elemento <ResourceURL>

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

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

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.

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>

O processo de configuração do TLS para um cliente HTTP é o mesmo que você usa para configurar o TLS para um TargetEndpoint/TargetServer. Consulte Como configurar o TLS do Edge para o back-end para mais informações.

Notas de uso

Uma política JavaScript não contém um código real. Em vez disso, uma política JavaScript faz referência a um "recurso" JavaScript e define a etapa no fluxo da API em que o JavaScript é executado. Você pode faça o upload do seu script por meio do editor de proxy da interface de gerenciamento ou inclua-o no /resources/jsc em proxies de API que você desenvolve localmente.

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 Trace. Para detalhes e exemplos, consulte Debug with JavaScript print().

Para ver instruções de impressão no Trace:

1. Abra a ferramenta Trace e inicie uma sessão de trace para um proxy que contenha a política do JavaScript.
2. Chame o proxy.
3. Na Ferramenta de trace, 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.

É possível usar a função print() para gerar informações de depuração para a ferramenta Trace. Essa função está disponível diretamente por meio do modelo de objeto JavaScript. Para mais detalhes, consulte "Depurar 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 do Apigee Edge.

Referência de erros

Esta seção descreve os códigos e mensagens de erro retornados e as variáveis de falha que são definidos pelo Edge quando esta política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém essa política.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Exemplo de resposta de erro

{
  "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>

Schema

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
• Para instruções, amostras de políticas e amostras de JavaScript, consulte Como programar proxies da API com o 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?