Política de JavaScript

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

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

No seu código JavaScript personalizado, pode usar os objetos, os métodos e as propriedades do modelo de objetos JavaScript do Apigee. Pode obter, definir e remover variáveis no contexto do fluxo do proxy, executar lógica personalizada, realizar o processamento de falhas, extrair dados de pedidos ou respostas e editar dinamicamente o URL de destino do back-end. Também pode usar funções criptográficas básicas que estão disponíveis no modelo de objetos.

A política de JavaScript permite-lhe especificar um ficheiro de origem JavaScript para executar ou pode incluir código JavaScript diretamente na configuração da política através do elemento <Source>. De qualquer forma, o código JavaScript é executado quando o passo ao qual a política está anexada é executado.

Para a opção de ficheiro de origem, o código-fonte é sempre armazenado numa localização padrão no pacote de proxy: apiproxy/resources/jsc. Em alternativa, pode armazenar o código-fonte num ficheiro de recursos ao nível do ambiente ou da organização. Para ver instruções, consulte o artigo Ficheiros de recursos. Também pode carregar JavaScript através do editor de proxy da IU do Apigee.

A Apigee não recomenda a utilização da política de JavaScript para o seguinte:

• Registo. A política MessageLogging é mais adequada para o registo com plataformas de registo de terceiros, como Splunk, Sumo e Loggly. Esta política também melhora o desempenho do proxy da API, uma vez que é executada no PostClientFlow depois de a resposta ser devolvida ao cliente.
• Substituir políticas do Apigee. A política de JavaScript não substitui as capacidades das políticas do Apigee. Se as capacidades de que precisa estiverem disponíveis numa política do Apigee, use essa política em vez de implementar uma solução JavaScript personalizada. O código JavaScript personalizado pode não corresponder ao desempenho e à otimização das políticas do Apigee.

Os ficheiros de origem JavaScript têm de ter uma extensão .js.

O Apigee suporta a execução de JavaScript no motor JavaScript Rhino 1.7.13.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Amostras

Reescrever o URL de destino

Um exemplo de utilização comum envolve a extração de dados de um corpo de pedido, o armazenamento dos mesmos numa variável de fluxo e, em seguida, a utilização dessa variável de fluxo noutro local no fluxo do proxy. Por exemplo, suponhamos que um utilizador introduz o respetivo nome num formulário HTML e o envia. Para extrair os dados do formulário e adicioná-los dinamicamente ao URL do serviço de back-end, use uma política de JavaScript.

Nota: para experimentar este exemplo, crie um novo proxy no editor de proxy. Quando criar o proxy, indique um URL do serviço de back-end, por exemplo, http://www.example.com. Este exemplo reescreve dinamicamente o URL de back-end. Se precisar de criar um novo proxy, consulte o tutorial de introdução.

1. Na IU do Apigee, abra o proxy que criou no editor de proxies.
2. Selecione o separador Desenvolver.
3. No menu Novo, selecione Novo script.
4. Na caixa de diálogo, selecione JavaScript e atribua o nome js-example ao script.
5. Cole o código seguinte no editor de código e guarde o proxy. O objeto context está disponível para o código JavaScript em qualquer parte do fluxo do proxy. Obtém constantes específicas do fluxo, chama métodos get/set úteis e realiza outras operações. Este objeto faz parte do modelo de objeto JavaScript do Apigee. A variável de fluxo target.url é uma variável incorporada de leitura/escrita acessível no fluxo de pedido de destino. Quando define essa variável com o URL da API, o Apigee chama esse URL de back-end. Isto reescreve o URL de destino original, que era o URL especificado quando criou 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. Atribua um nome à política target-rewrite. Aceite as predefinições e guarde a política.
8. Depois de selecionar o Preflow do ponto final do proxy no Navegador, a política é adicionada a esse fluxo.
9. No Navegador, selecione Target Endpoint PreFlow.
10. No Navigator, arraste a política de JavaScript para o lado do pedido do Ponto final de destino no editor de fluxo.
11. e clique em Guardar.
12. Substitua o nome da organização e o nome do proxy quando 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 XML da política de JavaScript usada neste exemplo. O elemento <ResourceURL> especifica o ficheiro de origem JavaScript a executar. Este padrão aplica-se a qualquer ficheiro de origem JavaScript: jsc://filename.js. Se o seu código JavaScript requerer 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>

Recupere o valor da propriedade do JavaScript

Pode adicionar um elemento <Property> na configuração e, em seguida, obter o respetivo valor com JavaScript em tempo de execução.

Use o atributo name do elemento para especificar o nome de acesso à propriedade a partir do código JavaScript. O valor do elemento <Property> (o valor entre as etiquetas de abertura e fecho) é o valor literal que o JavaScript recebe.

Em JavaScript, pode aceder ao valor da propriedade de política como uma propriedade do objeto Properties da seguinte forma:

• 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 através de JavaScript. Em seguida, a função getVariable usa o nome da variável obtido para obter 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);

Processamento de erros

Para ver exemplos e uma discussão sobre as técnicas de processamento de erros que pode usar numa chamada JavaScript, consulte o artigo Forma correta de devolver um erro de uma política de JavaScript. As sugestões na comunidade do Apigee destinam-se apenas a fins informativos e não representam necessariamente as práticas recomendadas pela Google.

Numa política de JavaScript, o acesso a request.content.asJSON no modo de leitura converte números inteiros grandes na notação exponencial no corpo da mensagem. Isto substitui a mensagem pelos valores convertidos.

Referência do elemento

A referência de elementos descreve os elementos e os atributos da política de 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	Predefinição	Presença
languageVersion	Especifica a versão da linguagem JavaScript em que o código está 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 gera este erro: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. Nota: para contas de avaliação sem custo financeiro, o tempo de execução está limitado a 200 ms.	N/A	Obrigatória

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 ficheiro de biblioteca JavaScript a carregar como uma dependência para o ficheiro JavaScript principal especificado com o elemento <ResourceURL> ou <Source>. A política avalia os scripts pela ordem em que são apresentados na política. O seu código pode usar os objetos, os métodos e as propriedades do modelo de objetos JavaScript.

Inclua mais do que um recurso de dependência JavaScript através de elementos <IncludeURL> adicionais.

Aviso: se os seus ficheiros JavaScript estiverem armazenados ao nível do proxy ou do ambiente, certifique-se de que os carrega corretamente com cURL através da opção -F ou como anexo de ficheiro através de um cliente REST. O Content-Type é multipart/form-data. Para mais informações, consulte o artigo Gerir recursos.

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

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

Elemento <Property>

Especifica uma propriedade à qual pode aceder a partir do código JavaScript no tempo de execução.

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

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

Atributos

Atributo	Descrição	Predefinição	Presença
nome	Especifica o nome da propriedade.	N/A	Obrigatória

Exemplo

Veja o exemplo na secção Exemplos.

Elemento <ResourceURL>

Especifica o ficheiro JavaScript principal que é executado no fluxo da API. Pode armazenar este ficheiro no âmbito do proxy da API (em /apiproxy/resources/jsc no pacote do proxy da API ou na secção Scripts do painel Navegador do editor do proxy da API). Em alternativa, armazene-o nos âmbitos da organização ou do ambiente para reutilização em vários proxies de API, conforme descrito em Gerir recursos. O seu código pode usar os objetos, os métodos e as propriedades do modelo de objetos JavaScript.

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

Predefinição:	Nenhum
Presença:	É necessário <ResourceURL> ou <Source>. Se estiverem presentes <ResourceURL> e <Source>, a política ignora <ResourceURL>.
Tipo:	String

Exemplo

Veja o exemplo na secção Exemplos.

Elemento <Source>

Pode inserir JavaScript diretamente na configuração XML da política. O código JavaScript inserido é executado quando a política é executada no fluxo da API.

Predefinição:	Nenhum
Presença:	É necessário <ResourceURL> ou <Source>. Se estiverem presentes <ResourceURL> e <Source>, a política ignora <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 de cliente HTTP criadas pela política de JavaScript.

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

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

O processo de configuração do TLS para um cliente HTTP é o mesmo processo usado para configurar o TLS para um TargetEndpoint/TargetServer. Consulte o artigo Opções para configurar o TLS para mais informações.

Notas de utilização

Aviso: o modelo de segurança não permite chamadas de sistema. Por exemplo, não são permitidas leituras ou escritas do sistema de ficheiros interno, informações do utilizador atual, listas de processos ou utilização da CPU/memória. Embora algumas chamadas possam ser funcionais, não são suportadas e estão sujeitas a desativação ativa em qualquer altura. Para compatibilidade futura, evite fazer estas chamadas no seu código.

Depurar código de 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 de depuração. Para ver detalhes e exemplos, consulte o artigo Depure JavaScript com declarações print().

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

1. Abra a ferramenta de depuração e inicie uma sessão de rastreio para um proxy que contenha a sua política de JavaScript.
2. Ligue ao proxy.
3. Na ferramenta de depuração, clique em Resultados de todas as transações para abrir o painel de resultados.

   

4. As suas declarações de impressão aparecem neste painel.

Variáveis do fluxo

Por predefinição, esta política não preenche nenhuma variável. No entanto, pode definir e obter variáveis de fluxo no seu código JavaScript chamando métodos no objeto context. Por exemplo:

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

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

Referência de erro

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

提示：需要我们帮助来解决错误？点击“修复”列中的 以获取详细的问题排查信息。

故障代码	HTTP 状态	原因	修复
steps.javascript.ScriptExecutionFailed	500	JavaScript 政策可能会抛出许多不同类型的 ScriptExecutionFailed 错误。 常见的错误类型包括：RangeError、ReferenceError、SyntaxError、TypeError 和 URIError。
steps.javascript.ScriptExecutionFailedLineNumber	500	JavaScript 代码中出现错误。请参阅故障字符串了解详情。	不适用
steps.javascript.ScriptSecurityError	500	JavaScript 执行时出现安全错误。请参阅故障字符串了解详情。	不适用

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

提示：需要我们帮助来解决错误？点击错误原因说明旁边的 即可访问问题排查页面。

错误名称	原因	修复
InvalidResourceUrlFormat	如果 JavaScript 政策的 <ResourceURL> 或 <IncludeURL> 元素中指定的资源网址格式无效，则 API 代理的部署将失败。
InvalidResourceUrlReference	如果 <ResourceURL> 或 <IncludeURL> 元素引用了不存在的 JavaScript 文件，则 API 代理的部署将失败。引用的源文件必须存在于 API 代理、环境或组织级别。
WrongResourceType	如果 JavaScript 政策的 <ResourceURL> 或 <IncludeURL> 元素引用除 jsc（JavaScript 文件）以外的任何资源类型，则会在部署期间出现此错误。
NoResourceURLOrSource	如果未声明 <ResourceURL> 元素或此元素内未定义资源网址，则 JavaScript 政策的部署可能会失败，并显示此错误。<ResourceURL> 元素是必需元素。或者，声明了 <IncludeURL> 元素，但未在此元素中定义资源网址。<IncludeURL> 元素是可选的，但如果声明，则必须在 <IncludeURL> 元素中指定资源网址。

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	其中	示例
fault.name="fault_name"	fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name 是抛出故障的政策的用户指定名称。	javascript.JavaScript-1.failed = true

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

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

故障规则示例

<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íticas estão disponíveis no GitHub.

Tópicos relacionados

• Modelo de objeto JavaScript

Artigos da comunidade do Apigee

Pode encontrar estes artigos relacionados na comunidade do Apigee:

• Como processar cabeçalhos com vários valores em JavaScript