Política de JavaScript

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

Veja a documentação do Apigee Edge.

O quê

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

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.

Acerca de

Existem muitos exemplos de utilização da política de JavaScript. Por exemplo, pode obter e definir variáveis de fluxo, executar lógica personalizada e realizar o processamento de falhas, extrair dados de pedidos ou respostas, editar dinamicamente o URL de destino do back-end e muito mais. Esta política permite-lhe implementar um comportamento personalizado que não é abrangido por outras políticas padrão do Apigee. Na verdade, pode usar uma política de JavaScript para alcançar muitos dos mesmos comportamentos implementados por outras políticas, como AssignMessage e ExtractVariable.

Um exemplo de utilização que não recomendamos para a política de JavaScript é o registo. A política MessageLogging é muito mais adequada para registar em plataformas de registo de terceiros, como Splunk, Sumo e Loggly, e melhora o desempenho do proxy da API executando a política MessageLogging no PostClientFlow, que é executado depois de a resposta ter sido enviada de volta para o cliente.

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 com o 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 do proxy: apiproxy/resources/jsc. Em alternativa, também 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 o seu JavaScript através do editor de proxy da IU do Apigee.

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

O Apigee suporta JavaScript executado no motor JavaScript Rhino 1.7.13.

Vídeo

Nota: o vídeo seguinte mostra o editor de proxy clássico na IU do Apigee. A Apigee está a introduzir uma nova versão do Proxy Editor, que tem um design diferente da versão clássica apresentada no vídeo.

Veja um vídeo curto para saber como criar uma extensão de política personalizada através da política de JavaScript.

Amostras

Reescrever o URL de destino

Seguem-se alguns exemplos de utilização comuns: extrair dados de um corpo do pedido, armazená-los numa variável de fluxo e usar essa variável de fluxo noutro local no fluxo do proxy. Suponhamos que tem uma app em que o utilizador introduz o respetivo nome num formulário HTML e o envia. Pretende que o proxy da API extraia os dados do formulário e os adicione dinamicamente ao URL usado para chamar o serviço de back-end. Como faria isto numa política de JavaScript?

Nota: se quiser experimentar este exemplo, partimos do princípio de que criou um novo proxy no editor de proxy. Quando o criar, basta atribuir-lhe um URL do serviço de back-end de: http://www.example.com. Para este exemplo, vamos reescrever o URL do back-end dinamicamente. Se não souber como 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 um nome ao script, como js-example.
5. Cole o código seguinte no editor de código e guarde o proxy. O importante a ter em atenção é o objeto context. Este objeto está disponível para o código JavaScript em qualquer parte do fluxo do proxy. É usado para obter constantes específicas do fluxo, chamar métodos get/set úteis e para mais operações. Esta parte do objeto faz parte do modelo de objeto JavaScript do Apigee. Tenha também em atenção que a variável de fluxo target.url é uma variável incorporada de leitura/escrita que é acessível no fluxo de pedido de destino. Quando definimos essa variável com o URL da API, o Apigee faz a chamada de back-end para esse URL. Reescrevemos essencialmente o URL de destino original, que era o que especificou 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, como target-rewrite. Aceite as predefinições e guarde a política.
8. Se selecionar o Preflow do ponto final do proxy no navegador, verá que a política foi adicionada a esse fluxo.
9. No navegador, selecione o ícone Target Endpoint PreFlow.
10. No navegador, 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. Chame a API da seguinte forma, substituindo o nome da organização e o nome do proxy corretos conforme adequado:

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

Por último, vamos analisar a definição XML da política de JavaScript usada neste exemplo. É importante ter em atenção que o elemento <ResourceURL> é usado para especificar o ficheiro de origem JavaScript a executar. Este mesmo padrão é usado para qualquer ficheiro de origem JavaScript: jsc://filename.js. Se o seu código JavaScript requer inclusões, pode usar um ou mais elementos <IncludeURL> para o fazer, 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>

Recupere o valor da propriedade do JavaScript

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

Use o atributo name do elemento para especificar o nome com o qual aceder à 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 será recebido pelo JavaScript.

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

• 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 obtido, ou seja, um nome de variável, é usado pela função getVariable 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 técnicas de processamento de erros que pode usar numa chamada de saída JavaScript, consulte o artigo Forma correta de devolver um erro da política de JavaScript. As sugestões oferecidas na comunidade do Apigee destinam-se apenas a informação e não representam necessariamente as práticas recomendadas pela Google.

Numa política de JavaScript, o acesso a request.content.asJSON apenas para leitura faz com que os números inteiros grandes sejam convertidos em notação exponencial no corpo da mensagem. Como resultado, a mensagem é substituída 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>

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

Os seguintes atributos são específicos desta política.

Atributo	Descrição	Predefinição	Presença
timeLimit	Especifica o tempo máximo (em milissegundos) que o script tem permissão para executar. Por exemplo, se for excedido um limite de 200 ms, a política gera este erro: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. Nota: para contas de avaliação gratuita, 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 ser carregado como dependência do ficheiro JavaScript principal especificado com o elemento <ResourceURL> ou <Source>. Os scripts são avaliados 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 de JavaScript com elementos <IncludeURL> adicionais.

Aviso: se os seus ficheiros JavaScript estiverem armazenados ao nível do proxy ou do ambiente, certifique-se de que foram carregados corretamente com o cURL através da opção -F ou como anexo de ficheiro através de um cliente REST. 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

Exemplo

Consulte o exemplo básico na secção Exemplos.

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ório.

Exemplo

Veja o exemplo na secção Exemplos.

Elemento <ResourceURL>

Especifica o ficheiro JavaScript principal que vai ser executado no fluxo da API. Pode armazenar este ficheiro no âmbito do proxy de API (em /apiproxy/resources/jsc no pacote do proxy de API ou na secção Scripts do painel Navigator do editor do proxy de API) ou 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 <ResourceURL> e <Source> estiverem presentes, <ResourceURL> é ignorado.
Tipo:	String

Exemplo

Consulte o exemplo básico na secção Exemplos.

Elemento <Source>

Permite-lhe 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 <ResourceURL> e <Source> estiverem presentes, <ResourceURL> é 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 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 que usa para configurar o TLS para um TargetEndpoint/TargetServer. Consulte as Opções de configuração do TLS para mais informações.

Notas de utilização

Aviso: as chamadas do sistema não são permitidas pelo modelo de segurança. Por exemplo: leituras ou escritas do sistema de ficheiros interno, ou obtenção de informações do utilizador atual, da lista de processos ou da utilização da CPU/memória. Embora algumas destas chamadas possam ser funcionais, não são suportadas e podem ser ativamente desativadas em qualquer altura. Para compatibilidade futura, deve evitar fazer essas 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 com declarações print() JavaScript.

Para ver declarações de impressão na 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. Os seus extratos de impressão são apresentados neste painel.

Pode usar a função print() para enviar informações de depuração para a ferramenta de depuração. Esta função está disponível diretamente através do modelo de objetos JavaScript. Para obter detalhes, consulte o artigo Depure JavaScript com declarações print().

Variáveis do fluxo

Esta política não preenche nenhuma variável por predefinição. No entanto, pode definir (e obter) variáveis de fluxo no seu código JavaScript chamando métodos no objeto de contexto. Um padrão típico tem o seguinte aspeto:

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

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

Referência de erro

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