Política de JavaScript

Política extensível

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

Confira a documentação da Apigee Edge.

A política JavaScript permite adicionar código JavaScript personalizado que é executado no contexto do fluxo de proxy de API. Essa política permite implementar um comportamento personalizado que não é coberto pelas políticas da Apigee.

No seu código JavaScript personalizado, é possível usar os objetos, métodos e propriedades do modelo de objeto JavaScript da Apigee. É possível receber, definir e remover variáveis no contexto de fluxo do proxy, executar lógica personalizada, realizar tratamento de falhas, extrair dados de solicitações ou respostas e editar dinamicamente o URL de destino do back-end. Também é possível usar funções criptográficas básicas disponíveis no modelo de objeto.

A política JavaScript permite especificar um arquivo de origem JavaScript a ser executado ou incluir código JavaScript diretamente na configuração da política usando 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 de JavaScript usando o editor de proxy da interface da Apigee.

Os arquivos de origem JavaScript precisam ter uma extensão .js. A Apigee é compatível com JavaScript executado no mecanismo JavaScript Rhino 1.7.13.

A Apigee não recomenda o uso da política JavaScript para o seguinte:

Geração de registros. A política MessageLogging é mais adequada para geração de registros com plataformas de geração de registros de terceiros, como Splunk, Sumo e Loggly. Essa política também melhora o desempenho do proxy de API ao ser executada no PostClientFlow depois que a resposta é retornada ao cliente.
Substituição de políticas da Apigee. A política JavaScript não substitui as capacidades das políticas do Apigee. Se os recursos necessários estiverem disponíveis em uma política da Apigee, use essa política em vez de implementar uma solução personalizada em JavaScript. O código JavaScript personalizado pode não corresponder à performance e à otimização das políticas da Apigee.
Para realizar chamadas do sistema. O modelo de segurança não permite chamadas do sistema da política de JavaScript. Por exemplo, não é permitido fazer leituras ou gravações internas do sistema de arquivos, acessar informações do usuário atual, listas de processos ou o uso da CPU/memória. Embora algumas chamadas possam ser funcionais, elas não são compatíveis e estão sujeitas a desativação ativa a qualquer momento. Para compatibilidade com versões futuras, evite fazer essas chamadas no seu código.

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.

Amostras

Reescrever o URL de destino

Um caso de uso comum envolve 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. Por exemplo, suponha que um usuário insira o nome em um formulário HTML e o envie. Para extrair os dados do formulário e adicioná-los dinamicamente ao URL do serviço de back-end, use uma política JavaScript.

Observação:para testar este exemplo, crie um novo proxy no editor de proxy. Ao criar o proxy, forneça um URL de serviço de back-end, por exemplo, http://www.example.com. Este exemplo reescreve dinamicamente o URL do back-end. Se você precisar criar um novo proxy, consulte o tutorial de primeiros passos.

Na interface da Apigee, abra o proxy que você criou no editor de proxy.
Selecione a guia Desenvolver.
No menu "Novo", selecione Novo script.
Na caixa de diálogo, selecione JavaScript e nomeie o script como js-example.
Cole o código a seguir no editor de código e salve o proxy. O objeto context está disponível para o código JavaScript em qualquer lugar no fluxo do proxy. Ele recebe constantes específicas do fluxo, chama métodos get/set úteis e realiza outras operações. Esse objeto faz parte do modelo de objeto JavaScript da Apigee. A variável de fluxo target.url é uma variável integrada de leitura/gravação acessível no fluxo de solicitação de destino. Quando você define essa variável com o URL da API, a Apigee chama esse URL de back-end. Isso reescreve o URL de destino original, que era o URL especificado 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);
}
```
No menu "Nova política", selecione JavaScript.
Nomeie a política como target-rewrite. Aceite os padrões e salve a política.
Depois de selecionar o Pré-fluxo do endpoint do proxy no Navegador, a política será adicionada a esse fluxo.
No Navegador, selecione Pré-fluxo do endpoint de destino.
No Navegador, arraste a política JavaScript para o lado da solicitação do endpoint de destino no editor de fluxo.
Salvar.
Substitua o nome da organização e do proxy ao chamar a API:

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

Examine a definição de XML para a política JavaScript usada neste exemplo. O elemento <ResourceURL> especifica o arquivo de origem JavaScript a ser executado. Esse padrão se aplica a qualquer arquivo de origem JavaScript: jsc://filename.js. Se o código JavaScript exigir inclusões, use um ou mais elementos <IncludeURL>, conforme descrito mais adiante neste documento.

<?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 dele 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 o JavaScript recebe.

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 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 usando JavaScript. A função getVariable usa o nome da variável recuperada para extrair o valor dela.

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

Em uma política do JavaScript, o acesso a request.content.asJSON no modo somente leitura converte números inteiros grandes em notação exponencial no corpo da mensagem. Isso substitui a mensagem 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>

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

Atributo	Descrição	Padrão	Presença
languageVersion	Especifica a versão da linguagem JavaScript em que o código foi escrito. Os valores incluem `VERSION_DEFAULT`, `VERSION_1_0`, `VERSION_1_1`, `VERSION_1_2`, `VERSION_1_3`, `VERSION_1_4`, `VERSION_1_5`, `VERSION_1_6`, `VERSION_1_7`, `VERSION_1_8` e `VERSION_ES6`.	VERSION_DEFAULT	Opcional
timeLimit	Especifica o tempo máximo (em milissegundos) que um script pode ser executado. 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 sem custo financeiro, o tempo de execução é limitado a 200 ms.	N/A	Obrigatório

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

Atributo	Descrição	Padrão	Presence
`name`	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
`continueOnError`	Defina como `false` para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como `true` para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
`enabled`	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
`async`	Esse atributo está obsoleto.	false	Descontinuado

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>

Padrão

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo `name` da política.
Presence	Opcional
Tipo	String

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presence Opcional

Tipo String

Elemento <IncludeURL>

Especifica um arquivo de biblioteca JavaScript que será carregado como dependência ao arquivo JavaScript principal especificado com o elemento <ResourceURL> ou <Source>. A política avalia os scripts na ordem em que estão listados. 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 usando elementos <IncludeURL> adicionais.

Aviso:se os arquivos JavaScript estiverem armazenados no nível do proxy 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

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	Presença
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 é 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 Navegador do editor de proxy de API). Como alternativa, armazene-o nos escopos da organização ou do 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, a política vai ignorar `<ResourceURL>`.
Tipo:	String

Exemplo

Veja o exemplo na seção Amostras.

Elemento <Source>

É possível 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, a política vai ignorar `<ResourceURL>`.
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 usado para configurar o TLS para um TargetEndpoint/TargetServer. Saiba mais em Opções para configurar o TLS.

Usar JavaScript para processar erros

É possível usar a política JavaScript para processar e retornar erros. Para uma discussão sobre esse tema, consulte Forma correta de retornar um erro de uma política JavaScript na Comunidade Apigee. As postagens e os comentários da comunidade não representam necessariamente as práticas recomendadas pela Apigee.

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 Depurar JavaScript com instruções print().

Para ver instruções de impressão na ferramenta de depuração:

Abra a ferramenta Debug e inicie uma sessão de trace para um proxy que contenha a política do JavaScript.
Chame o proxy.
Na ferramenta de depuração, clique na política JavaScript e na guia Propriedades para ver a propriedade "stepExecution-stdout" mostrando a saída da instrução de impressão.
Suas declarações de impressão aparecem neste painel.

Variáveis de fluxo

Essa política não preenche nenhuma variável por padrão. No entanto, é possível definir e receber variáveis de fluxo no código JavaScript chamando métodos no objeto context. Exemplo:

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

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

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
`steps.javascript.ScriptExecutionFailed`	`500`	The `JavaScript` policy can throw many different types of `ScriptExecutionFailed` errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
`steps.javascript.ScriptExecutionFailedLineNumber`	`500`	An error occurred in the `JavaScript` code. See the fault string for details.	N/A
`steps.javascript.ScriptSecurityError`	`500`	A security error occurred when the `JavaScript` executed. See the fault string for details.	N/A

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidResourceUrlFormat`	If the format of the resource URL specified within the `<ResourceURL>` or the `<IncludeURL>` element of the `JavaScript` policy is invalid, then the deployment of the API proxy fails.
`InvalidResourceUrlReference`	If the `<ResourceURL>` or the `<IncludeURL>` elements refer to a `JavaScript` file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
`WrongResourceType`	This error occurs during deployment if the `<ResourceURL>` or the `<IncludeURL>` elements of the `JavaScript` policy refer to any resource type other than jsc (`JavaScript` file).
`NoResourceURLOrSource`	The deployment of the `JavaScript` policy can fail with this error if the `<ResourceURL>` element is not declared or if the resource URL is not defined within this element. `<ResourceURL>` element is a mandatory element. Or, The `<IncludeURL>` element is declared but the resource URL is not defined within this element. The `<IncludeURL>` element is optional but if declared, the resource URL must be specified within the `<IncludeURL>` element.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "ScriptExecutionFailed"`
`javascript.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`javascript.JavaScript-1.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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

Política de JavaScript Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Amostras

Reescrever o URL de destino

Recuperar valor de propriedade do JavaScript

Referência de elemento

Atributos <JavaScript>

Elemento <DisplayName>

Elemento <IncludeURL>

Elemento <Property>

Atributos

Exemplo

Elemento <ResourceURL>

Exemplo

Elemento <Source>

Exemplo

Elemento <SSLInfo>

Usar JavaScript para processar erros

Depurar o código da política JavaScript

Variáveis de fluxo

Referência de erros

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Esquema

Temas relacionados

Artigos da comunidade Apigee

Política de JavaScript