Modelo de objeto JavaScript

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

Ver documentação do Apigee Edge.

Este tópico aborda o modelo de objetos JavaScript do Apigee. É importante compreender este modelo se pretender usar a política de JavaScript para adicionar JavaScript personalizado a um proxy de API.

Acerca do modelo de objetos JavaScript

O modelo de objeto JavaScript define objetos com propriedades associadas que estão disponíveis para o código JavaScript que é executado num fluxo de proxy do Apigee. Use a política de JavaScript para anexar este código personalizado a um fluxo de proxy de API.

Os objetos definidos por este modelo têm âmbito no fluxo do proxy da API, o que significa que determinados objetos e propriedades só estão disponíveis em pontos específicos do fluxo. Quando o seu JavaScript é executado, é criado um âmbito para a execução. Nesse âmbito, são criadas estas referências de objetos:

• context: um objeto que fornece acesso ao contexto da mensagem
• request: uma abreviatura que permite o acesso ao objeto de pedido
• response: uma abreviatura que permite o acesso ao objeto de resposta
• crypto: fornece várias funções hash
• print: uma função para emitir resultados
• properties: permite o acesso de leitura às propriedades de configuração na política

O objeto de contexto

O objeto context tem âmbito global. Está disponível em todas as localizações no fluxo de proxy da API. Tem quatro objetos subordinados: proxyRequest, proxyResponse, targetRequest e targetResponse. Estes objetos secundários estão no âmbito do pedido e da resposta do ambiente, quer seja o pedido e a resposta do proxy ou o pedido e a resposta de destino. Por exemplo, se a política de JavaScript for executada na parte do ponto final do proxy do fluxo, os objetos context.proxyRequest e context.proxyResponse estão no âmbito. Se o JavaScript for executado num fluxo de destino, os objetos context.targetRequest e context.targetResponse estão no âmbito.

O objeto context também tem propriedades e métodos, que são descritos detalhadamente neste tópico. Por exemplo, o seguinte exemplo de código JavaScript usa a propriedade context.flow e chama os métodos get/setVariable() em context.

if (context.flow=="PROXY_REQ_FLOW") {
     var username = context.getVariable("request.formparam.user");
     context.setVariable("USER.name", username);
}

Estes métodos interagem diretamente com as variáveis de fluxo. O valor da propriedade context.flow é o âmbito do fluxo atual. No fluxo de pedidos de proxy, é definido como a constante PROXY_REQ_FLOW. Se, no fluxo de resposta de destino, estiver definido como TARGET_RESP_FLOW. Esta constante é útil para executar código específico do âmbito. O getter permite-lhe obter variáveis de fluxo e o setter permite-lhe definir variáveis de fluxo. Geralmente, estas variáveis estão disponíveis no fluxo de proxy e podem ser consumidas por outras políticas.

Consulte a referência do objeto de contexto para ver mais detalhes e exemplos.

O objeto cripto

O objeto crypto adiciona suporte criptográfico básico de alto desempenho ao modelo de objeto JavaScript. Consulte a referência de objetos criptográficos para ver mais detalhes e exemplos.

Os objetos de pedido e resposta

Os objetos request e response são referências abreviadas ao pedido e à resposta ambiente, quer o pedido e a resposta do proxy, quer o pedido e a resposta de destino. Os objetos a que estas variáveis se referem dependem do contexto em que a política de JavaScript é executada. Se o JavaScript for executado no fluxo de um ponto final de proxy, as variáveis de pedido e resposta referem-se a context.proxyRequest e context.proxyResponse. Se o JavaScript for executado num fluxo de destino, as variáveis referem-se a context.targetRequest e context.targetResponse.

A função print()

O modelo de objeto JavaScript inclui uma função print() que pode usar para gerar informações de depuração na ferramenta de depuração do Apigee. Consulte o artigo Depure com declarações print() de JavaScript.

O objeto properties

Quando usar um elemento Properties na configuração da política, o código JavaScript pode aceder aos valores dessas propriedades através da variável properties.

Por exemplo, se a sua configuração JavaScript contiver:

<Javascript name='JS-1' >
  <Properties>
    <Property name="number">8675309</Property>
    <Property name="firstname">Jenny</Property>
  </Properties>
  <ResourceURL>jsc://my-code.js</ResourceURL>
</Javascript>

Em seguida, em my-code.js, pode:

  print(properties.firstname);  // prints Jenny
  print(properties.number);  // 8675309

De forma mais prática, a configuração pode permitir que o código se comporte de forma diferente quando executado em ambientes diferentes, em momentos diferentes ou por qualquer motivo.

Por exemplo, o seguinte especifica o "nome da variável" e o estilo de saída para o qual o JavaScript deve emitir informações:

<Javascript name='JS-2' >
  <Properties>
    <Property name="output">my_output_variable</Property>
    <Property name="prettyPrint">true</Property>
  </Properties>
  <ResourceURL>jsc://emit-results.js</ResourceURL>
</Javascript>

Em seguida, em emit-results.js, o código pode fazer o seguinte:

var result = { prop1: "something", prop2 : "something else" } ;
if (properties.prettyPrint == "true") {
  context.setVariable(properties.output, JSON.stringify(result, null, 2));
}
else {
  context.setVariable(properties.output, JSON.stringify(result));
}

Referência do objeto cripto

O objeto crypto permite-lhe executar funções de hash criptográficas básicas em JavaScript.

Nota: as funções criptográficas suportam apenas a aplicação de hash. Não existe suporte para encriptação bidirecional.

O objeto cripto tem âmbito global. Está disponível em qualquer lugar no fluxo do proxy de API. A API Crypto permite-lhe trabalhar com os seguintes objetos hash:

• SHA-1
• SHA256
• SHA512
• MD5

Dica: o Apigee recomenda que use o objeto criptográfico para executar funções criptográficas básicas nos seus programas JavaScript executados no Apigee.

Trabalhar com objetos SHA-1

Pode criar objetos SHA-1, atualizá-los e convertê-los em valores hexadecimais e base64.

Crie um novo objeto SHA-1

var _sha1 = crypto.getSHA1();

Atualize um objeto SHA-1

Sintaxe

_sha1.update(value);

Parâmetros

• valor: (string) qualquer valor de string.

Exemplo

Atualize um objeto SHA-1:

_sha1.update("salt_value");

_sha1.update("some text");

Devolve o objeto SHA-1 como uma string hexadecimal

var _hashed_token = _sha1.digest();

Devolve o objeto SHA-1 como uma string base64

var _hashed_token = _sha1.digest64();

Trabalhar com objetos SHA-256

Pode criar objetos SHA-256, atualizá-los e convertê-los em valores hexadecimais e base64.

Crie um novo objeto SHA-256

var _sha256 = crypto.getSHA256();

Atualize um objeto SHA-256

Sintaxe

_sha256.update(value);

Parâmetros

• valor: (string) qualquer valor de string.

Exemplo

Atualize um objeto SHA-256:

_sha256.update("salt_value");

_sha256.update("some text");

Devolva o objeto SHA-256 como uma string hexadecimal

var _hashed_token = _sha256.digest();

Devolva o objeto SHA-256 como uma string base64

var _hashed_token = _sha256.digest64();

Trabalhar com objetos SHA-512

Pode criar objetos SHA-512, atualizá-los e convertê-los em valores hexadecimais e base64.

Crie um novo objeto SHA-512

var _sha512 = crypto.getSHA512();

Atualize um objeto SHA-512

Sintaxe

_sha512.update(value);

Parâmetros

• valor: (string) qualquer valor de string.

Exemplo

Atualize um objeto SHA-512:

_sha512.update("salt_value");

_sha512.update("some text");

Devolve o objeto SHA-512 como uma string hexadecimal

var _hashed_token = _sha512.digest();

Devolva o objeto SHA-512 como uma string base64

var _hashed_token = _sha512.digest64();

Trabalhar com objetos MD5

Pode criar objetos MD5, atualizá-los e convertê-los em valores hexadecimais e base64.

Crie um novo objeto MD5

var _md5 = crypto.getMD5();

Atualize um objeto MD5

Sintaxe

_md5.update(value);

Parâmetros

• valor: (string) qualquer valor de string.

Exemplo

Atualize um objeto MD5:

_md5.update("salt_value");

_md5.update("some text");

Devolve o objeto MD5 como uma string hexadecimal

var _hashed_token = _md5.digest();

Devolva o objeto MD5 como uma string base64

var _hashed_token = _md5.digest64();

Suporte de data/hora de criptomoedas

O objeto crypto suporta padrões de formatação de data/hora.

crypto.dateFormat()

Devolve uma data no formato de string.

Sintaxe

crypto.dateFormat(format, [timezone], [time])

Parâmetros

• format: (string) a implementação subjacente para este parâmetro é java.text.SimpleDateFormat. Por exemplo: "AAAA-MM-DD HH:mm:ss.SSS"
• timezone: (string, opcional) A implementação subjacente deste parâmetro é java.util.TimeZone. Este parâmetro é o mesmo que o valor predefinido: UTC
• hora: (número, opcional) um valor de data/hora Unix a formatar. Predefinição: hora atual

Exemplos

Nota: a documentação java.text.SimpleDateFormat fornece uma lista completa de todos os carateres de formatação de data/hora e combinações de carateres, bem como exemplos detalhados.

Obter a hora atual, até aos milissegundos:

var _now = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS');

Saber a hora atual do fuso horário do Pacífico:

var _pst = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST');

Obter o valor de dez segundos a partir de agora:

var _timeNow = Number(context.getVariable('system.timestamp'));
var tenSeconds = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST', _timeNow + 10 * 1000);

Exemplos adicionais. Consulte também a documentação java.text.SimpleDateFormat.

var _pst = crypto.dateFormat('M');

var _pst = crypto.dateFormat('EEE, d MMM yyyy HH:mm:ss Z');

var _pst = crypto.dateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");

Proteja documentos SOAP com WS-Security e certificados X.509

Proteja documentos SOAP com WS-Security com assinatura digital RSA/X.509.

crypto.wsSecRsaSign()

Assina o documento SOAP e devolve a carga útil assinada.

Sintaxe

crypto.wsSecRsaSign(payload, options)

Parâmetros

• payload: (string) documento SOAP a assinar.
• options: (objeto) opções de configuração para a assinatura digital. A tabela seguinte indica as opções de configuração disponíveis. Todos os valores das opções podem ser strings literais ou modelos de mensagens, indicados pela utilização dos carateres do modelo '{' e '}'.

  Nome	Obrigatório?	Descrição
  certificate	Obrigatória	Certificado correspondente à chave privada no formato PEM.
  private_key	Obrigatória	Variável de fluxo que contém a chave privada no formato PEM.
  c14_inclusive_elements	Opcional	Lista separada por vírgulas de URIs de espaço de nomes (não prefixos) usados para adicionar um elemento InclusiveElements ao elemento CanonicalizationMethod.
  confirmation	Opcional	Uma das seguintes opções: Lista de valores de assinatura em elementos SignatureConfirmation a serem assinados. Se não estiver presente um elemento SignatureConfirmation com o valor especificado, este é injetado. \*all\* string que indica que todos os elementos SignatureConfirmation existentes no documento de origem vão ser assinados. String vazia que indica a injeção de um elemento SignatureConfirmation vazio. Estas assinaturas de confirmação são adicionais aos elementos especificados em elements-to-sign.
  digest_method	Opcional	Algoritmo de resumo. Os valores válidos são sha1 ou sha256. A predefinição é sha256.
  ds_prefix	Opcional	String simples a usar como prefixo para o espaço de nomes.
  elements_to_sign	Opcional	Matriz de expressões XPath para elementos a assinar (por exemplo, ["soapenv:Body"]).
  expiry	Opcional	Valores a injetar no elemento Expires do Timestamp. Introduza valores como 120s, 10m e 4d para indicar 120 segundos, 10 minutos e 4 dias. A predefinição é sem prazo de validade.
  ignore_security_header_placement	Opcional	Valor booleano que especifica se deve verificar o posicionamento do cabeçalho Security existente no payload não assinado. Disponibilizado para compatibilidade com alguns sistemas antigos. A definição para true não é recomendada porque pode expôr a sua API a ataques de encapsulamento de assinaturas. A predefinição é false.
  issuer_name_style	Opcional	Formato do nome do emissor. Os valores válidos são CN ou DN.
  key_identifier_type	Opcional	Tipo de identificador de chave. Os valores válidos são BinarySecurityToken, BST_DIRECT_REFERENCE, ISSUER_SERIAL, RSA_KEY_VALUE, THUMBPRINT e X509_CERT_DIRECT. A predefinição é BinarySecurityToken.
  private_key_password	Opcional	Chave de palavra-passe, se a chave privada estiver encriptada.
  signing_method	Opcional	Método usado para assinar. Os valores válidos são rsa-sha1 ou rsa-sha256. A predefinição é rsa-sha1; no entanto, é altamente recomendável definir como rsa-sha256.
  soap_version	Opcional	Versão SOAP. As versões válidas são 1.1 e 1.2. A predefinição é 1,1.
  transform_inclusive_elements	Opcional	Lista separada por vírgulas de URIs de espaço de nomes (não prefixos) usados para adicionar um elemento InclusiveElements ao elemento Transform.

Exemplo

O exemplo seguinte mostra como assinar um documento SOAP. Assume que a chave privada e o certificado são carregados em variáveis de fluxo.

var signed = crypto.wsSecRsaSign(request.content, {
    'private_key': '{private.key.pem}', // Flow variable name
    'certificate': '{public.cert.pem}', // Flow variable name
    'elements_to_sign: 
        'wsu:Timestamp, soap:Body, wsa:To, wsa:MessageID',
    'signing_method': 'rsa-sha256',
    'digest_method': 'sha256',
    expires_in': '180s'
});

Valide documentos SOAP através da WS-Security com certificados X.509

Valida a assinatura digital de um documento SOAP através de WS-Security com RSA/X.509. Gaambo faz a validação para garantir que os argumentos transmitidos são válidos.

crypto.wsSecRsaValidate()

Valida a assinatura digital de um documento SOAP.

Sintaxe

crypto.wsSecRsaValidate(payload, options)

Parâmetros

• payload: (string) documento SOAP com assinatura digital a validar.
• options: (objeto) opções de configuração para validação. A tabela seguinte indica as opções de configuração disponíveis. Todos os valores das opções podem ser strings literais ou modelos de mensagens, indicados pela utilização dos carateres do modelo '{' e ''}'.

  Nome	Obrigatório?	Descrição
  accept_subject_cns	Opcional	Lista separada por vírgulas de nomes comuns (CNs) para o assunto que são signatários aceitáveis. Se alguma assinatura for de um CN que não corresponda a um dos CNs especificados, a validação falha.
  accept_thumbprints	Opcional	Lista separada por vírgulas de impressões digitais SHA-1 dos certificados que são signatários aceitáveis. Se qualquer assinatura for de um certificado com uma impressão digital que não corresponda a uma das impressões digitais especificadas, a validação falha. Especifique apenas um de accept-thumbprints ou accept-thumbprints-256. É necessária, pelo menos, uma destas opções se a opção certificate não for facultada.
  accept_thumbprints_256	Opcional	Lista separada por vírgulas de impressões digitais SHA-256 dos certificados que são signatários aceitáveis. Se qualquer assinatura for de um certificado com uma impressão digital que não corresponda a uma das impressões digitais especificadas, a validação falha. Especifique apenas um de accept-thumbprints ou accept-thumbprints-256. É necessária, pelo menos, uma destas opções se a opção certificate não for facultada.
  certificate	Opcional	Certificado que fornece a chave pública para validar a assinatura. Obrigatório e usado apenas se KeyInfo no documento assinado não fornecer explicitamente o certificado.
  digest_method	Opcional	Método de resumo suportado. Os valores válidos são sha1 ou sha256. Se for omitido, o método de resumo não é verificado.
  ignore_certificate_expiry	Opcional	Valor booleano que especifica se as datas de validade no certificado fornecido devem ser ignoradas. Útil para testes. A predefinição é false.
  ignore_expiry	Opcional	Valor booleano que especifica se o campo Timestamp/Expires deve ser ignorado ao avaliar a validade do documento SOAP. A predefinição é false.
  ignore_security_header_placement	Opcional	Valor booleano que especifica se deve verificar o posicionamento do cabeçalho de segurança no payload assinado. Disponibilizado para compatibilidade com alguns sistemas antigos. A definição desta opção como true não é recomendada, uma vez que pode expor as APIs a ataques de encapsulamento de assinaturas. A predefinição é false.
  issuer_name_dn_comparison	Opcional	Método usado para determinar se dois nomes de emissor se referem à mesma entidade. Aplica-se apenas se o documento assinado incluir KeyInfo que envolve X509IssuerSerial e o issuer-name-style for DN (a predefinição). O valor pode ser um dos seguintes: {string, normal, reverse, unordered}. A predefinição é string.
  issuer_name_dn_comparison_exclue_numeric_oids	Opcional	Método usado para determinar se os dois nomes de emissor se referem à mesma entidade. Aplica-se apenas se o documento assinado incluir KeyInfo que envolve X509IssuerSerial e o issuer-name-style for DN (o valor predefinido) e o issuer-name-dn-comparison estiver definido como normal, reverse ou unordered.
  issuer_name_style	Opcional	Formato do nome do emissor. Usado apenas se o documento assinado incluir um KeyInfo que envolva X509IssuerSerial. Os valores válidos incluem CN ou DN.
  max_lifetime	Opcional	Duração máxima do documento assinado. Introduza um valor como 120s, 10m e 4d para indicar 120 segundos, 10 minutos e 4 dias. Esta opção requer que o elemento Timestamp inclua um elemento Created e um elemento Expires. A predefinição é não ter uma duração total máxima.
  require_expiry	Opcional	Valor booleano que especifica se é necessária uma data de validade na data/hora. Recomendamos que este valor permaneça definido como true. A predefinição é true.
  required_sign_elements	Opcional	Lista separada por vírgulas ou espaços de formulários prefix:Tag que indicam os elementos que têm de ser assinados. A predefinição é soap:Body, wsu:Timestamp. Para exigir apenas uma assinatura na data/hora e não no corpo durante a validação, defina este valor como wsu:Timestamp. Para exigir apenas uma assinatura no corpo e não a data/hora durante a validação, defina este valor como soap:Body. O prefixo e a etiqueta são sensíveis a maiúsculas e minúsculas. Recomendamos que deixe este valor definido como o predefinido, a menos que tenha um motivo específico para o alterar.
  signing_method	Opcional	Método de assinatura que tem de corresponder ao método de assinatura no documento assinado. Os valores válidos são rsa-sha1 ou rsa-sha256. Se for omitido, o método de assinatura não é verificado.

Exemplo

O exemplo seguinte mostra como validar a API baseada em SOAP assinada. Se a assinatura for inválida, a variável de fluxo wssec_error é preenchida com o erro específico.

Var isValid = crypto.wsSecRsaValidate(request.content, {
        MaxLifetime: '300s',
        RequiredSignedElements: [
            '//*[local-name()=\'Body\']'
        ],
        IgnoreCertificateExpiry: false,
        TrustStore: '{truststore.pem}' // Flow variable with trusted certs
    });

 if (!isValid) {
   throw "invalid"
 }

Use getHash() para obter qualquer um dos objetos hash suportados

Exemplos

var _hash1 = crypto.getHash('MD5');

var _hash2 = crypto.getHash('SHA-1');

var _hash3 = crypto.getHash('SHA-256');

var _hash4 = crypto.getHash('SHA-512');

Exemplo com criptomoedas

try {
    // get values to use with hash functions
    var salt = context.getVariable("salt") || 'SomeHardCodedSalt';
    var host = context.getVariable("request.header.Host");
    var unhashedToken = "";

    var _timeNow = Number(context.getVariable('system.timestamp'));
    var now = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST', _timeNow);
    unhashed_token = "|" + now + "|" + host

    // generate a hash with the unhashedToken:
    var sha512 = crypto.getSHA512();
    sha512.update(salt);
    sha512.update(unhashedToken);

    // convert to base64
    var base64Token = sha512.digest64();

    // set headers
    context.setVariable("request.header.now", now);
    context.setVariable("request.header.token", base64Token);

} catch(e) {
    throw 'Error in Javascript';
}

Referência do objeto de contexto

• context object summary
• métodos do objeto de contexto
• propriedades do objeto de contexto
• context object children

É criado um objeto context para cada transação de pedido/resposta executada por um proxy de API. O objeto context expõe métodos para obter, definir e remover variáveis relacionadas com cada transação.

As variáveis definem propriedades específicas de uma transação. A hora do dia, a localização do cliente que faz o pedido, o agente do utilizador do cliente que faz o pedido e o URL do serviço de destino são todos exemplos de variáveis que estão disponíveis no context. Por conseguinte, context é útil para criar lógica que dependa destas propriedades para executar um comportamento personalizado.

Consulte a referência de variáveis de fluxo e a política ExtractVariables.

context object summary

Esta tabela descreve brevemente o objeto de contexto e os respetivos elementos subordinados, e apresenta as propriedades associadas a cada um.

Nome	Descrição	Propriedades
context	Um contentor para o contexto do pipeline de processamento de mensagens e os fluxos de pedidos e respostas que são executados pelo ProxyEndpoint e TargetEndpoint.	flow, session
context.proxyRequest	Um objeto que representa a mensagem de pedido de entrada para o ProxyEndpoint (da app que faz o pedido para o proxy de API)	cabeçalhos, parâmetros de consulta, método, corpo, URL
context.targetRequest	Um objeto que representa a mensagem de pedido de saída do TargetEndpoint (do proxy de API para o serviço de back-end).	cabeçalhos, parâmetros de consulta, método, corpo, URL
context.targetResponse	Um objeto que representa a mensagem de resposta do destino de entrada (do serviço de back-end para o proxy de API)	cabeçalhos, conteúdo, estado
context.proxyResponse	Um objeto que representa a mensagem de resposta do proxy de saída (do proxy da API para a app que está a fazer o pedido)	cabeçalhos, conteúdo, estado
context.flow	O nome do fluxo atual.	Consulte context.flow.
context.session	Um mapa de pares de nome/valor que pode usar para transmitir objetos entre dois passos diferentes em execução no mesmo contexto. Por exemplo: context.session['key'] = 123.	Para mais informações sobre quando e quando não usar este objeto, consulte Qual é a diferença entre context.session['hello'] = {} e context.setVariable("hello", {}).

context object methods

context.getVariable()

Recupera o valor de uma variável predefinida ou personalizada.

Sintaxe

context.getVariable("variable-name");

Exemplo

Para obter o valor do ano atual:

var year = context.getVariable('system.time.year');

context.setVariable()

Define o valor de uma variável personalizada ou de quaisquer variáveis predefinidas graváveis.

Sintaxe

context.setVariable("variable-name", value);

Exemplo

Um cenário comum para definir uma variável é quando um proxy de API tem de escrever dinamicamente o URL de destino. O JavaScript seguinte obtém o valor de uma variável denominada USER.name, anexa esse valor como um parâmetro de consulta ao URL http://mocktarget.apigee.net?user= e, em seguida, define o valor target.url predefinido para esse valor.

context.setVariable("target.url", "http://mocktarget.apigee.net/user?user="+context.getVariable("USER.name"));

Dica: qualquer variável predefinida gravável e qualquer variável personalizada podem ser definidas dinamicamente a partir do JavaScript. Para ver uma lista completa das variáveis predefinidas, consulte a referência de variáveis de fluxo.

context.removeVariable()

Remove uma variável do contexto.

Sintaxe

context.removeVariable('variable-name');

propriedades do objeto de contexto

context.flow

A propriedade flow é uma string que identifica o fluxo de proxy da API atual. Esta propriedade é usada para indicar o fluxo ao qual o JavaScript está anexado. Os valores suportados são:

• PROXY_REQ_FLOW
• PROXY_RESP_FLOW
• TARGET_REQ_FLOW
• TARGET_RESP_FLOW

Cada nome de fluxo abrange o PreFlow, o PostFlow e todos os fluxos condicionais definidos nos ProxyEndpoints ou TargetEndpoints.

Esta propriedade opcional é útil quando o JavaScript comum é executado em mais do que um fluxo, mas pode variar o respetivo comportamento consoante o fluxo no qual é executado. Use a propriedade Flow para módulos JavaScript destinados a serem reutilizados em vários proxies de API, nos quais o código é necessário para verificar o Flow atual antes de executar a lógica.

Exemplo

Defina um cabeçalho HTTP apenas no fluxo targetRequest:

if (context.flow=="TARGET_REQ_FLOW") {
     context.targetRequest.headers['TARGET-HEADER-X']='foo';
}

Defina o conteúdo apenas no fluxo proxyResponse:

if (context.flow=="PROXY_RESP_FLOW") {
     context.proxyResponse.content='bar';
}

context.session

Um mapa de pares de nome/valor que pode ser usado para transmitir objetos entre duas políticas em execução no mesmo contexto de mensagem.

Nota: é importante compreender a diferença entre usar context.session para obter/definir variáveis e usar context.getVariable() e context.setVariable(). Consulte esta discussão da comunidade do Apigee para mais detalhes.

Exemplo

Defina um valor na sessão:

context.session['key']  = 123;

Obtenha o valor da sessão:

var value = context.session['key']; // 123

Exemplo: para um exemplo funcional que usa o objeto context.session, consulte o exemplo de proxy da API de chamada assíncrona.

context object children

Conforme mostrado abaixo, um fluxo de proxy de API completo abrange quatro fases distintas, cada uma das quais tem um objeto de mensagem associado que é um elemento secundário do objeto de contexto:

• context.proxyRequest: A mensagem de pedido recebida do cliente que está a fazer o pedido.
• context.targetRequest: a mensagem de pedido de saída enviada para o serviço de back-end.
• context.proxyResponse: A mensagem de resposta de saída devolvida ao cliente que fez o pedido.
• context.targetResponse: a mensagem de pedido recebida do serviço de back-end.

As secções seguintes descrevem os métodos e as propriedades destes objetos:

• context.*Request child objects
• context.*Response child objects

context.*Request child objects

Para cada transação HTTP executada num proxy de API, são criados dois objetos de mensagens de pedido: um de entrada (o pedido do cliente) e um de saída (o pedido gerado pelo proxy de API e enviado para o destino de back-end).

O objeto context tem objetos secundários que representam estas mensagens de pedido: context.proxyRequest e context.targetRequest. Estes objetos permitem-lhe aceder a propriedades no fluxo de pedidos que estão no âmbito quando o seu código JavaScript é executado.

Nota: também pode usar o objeto shorthand request para aceder a estas propriedades num fluxo de pedidos. O objeto request refere-se a context.proxyRequest ou context.targetRequest, consoante o ponto do fluxo em que o código JavaScript é executado.

context.*Request child object properties

Nome de propriedade	Descrição
url	A propriedade url é uma propriedade de conveniência de leitura/escrita que combina o esquema, o anfitrião, a porta, o caminho e os parâmetros de consulta para o targetRequest. O URL completo do pedido é composto pelas seguintes propriedades: protocol: o protocolo do URL (por exemplo, HTTP, HTTPS) porta: a porta (por exemplo, :80, :443) host: o anfitrião do URL (por exemplo, www.example.com) path: o caminho do URI (por exemplo, /v1/mocktarget) Quando obtém url, é devolvido um URL no seguinte formato: protocol://host:port/path?queryParams
	Exemplos: context.targetRequest.url = 'http://www.example.com/path?q1=1' context.targetRequest.protocol ='https';
headers	Cabeçalhos do pedido HTTP como um mapeamento de String => List
	Exemplos: Para este pedido HTTP: POST /v1/blogs HTTP/1.1 Host: api.example.com Content-Type: application/json Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z O seguinte JavaScript: context.proxyRequest.headers['Content-Type']; context.proxyRequest.headers['Authorization']; devolve os seguintes valores application/json Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z
queryParams	Os parâmetros de consulta da mensagem de pedido como um mapeamento de String => List.
	Exemplos: "?city=PaloAlto&city=NewYork" pode ser acedido como: context.proxyRequest.queryParams['city']; // == 'PaloAlto' context.proxyRequest.queryParams['city'][0] // == 'PaloAlto' context.proxyRequest.queryParams['city'][1]; // == 'NewYork' context.proxyRequest.queryParams['city'].length(); // == 2
method	O verbo HTTP (GET, POST, PUT, DELETE). PATCH, etc.) associado ao pedido
	Exemplos: Para esta solicitação: POST /v1/blogs HTTP/1.1 Host: api.example.com Content-Type: application/json Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z O seguinte JavaScript: context.proxyRequest.method; devolve o seguinte valor POST
body	O corpo da mensagem (carga útil) do pedido HTTP. O corpo do pedido tem os seguintes membros: context.targetRequest.body.asXML; context.targetRequest.body.asJSON; context.targetRequest.body.asForm;
	Exemplos: Para um corpo XML: <customer number='1'> <name>Fred<name/> <customer/> Para aceder aos elementos do objeto XML da seguinte forma: var name = context.targetRequest.body.asXML.name; Para aceder aos atributos XML, use a notação @. var number = context.targetRequest.body.asXML.@number; Para um corpo do pedido JSON: { "a": 1 , "b" : "2" } var a = context.proxyRequest.body.asJSON.a; // == 1 var b = context.proxyRequest.body.asJSON.b; // == 2 Para ler parâmetros de formulário: "vehicle=Car&vehicle=Truck" v0 = context.proxyRequest.body.asForm['vehicle'][0]; v1 = context.proxyRequest.body.asForm['vehicle'][1];

context.*Response child objects

Para cada transação HTTP executada num proxy de API, são criados dois objetos de mensagens de resposta: um inbound (a resposta do serviço de back-end) e um outbound (a resposta enviada de volta ao cliente).

O objeto de contexto tem objetos secundários que representam estas mensagens de resposta: context.proxyResponse e context.targetResponse. Estes objetos permitem-lhe aceder a propriedades no fluxo de resposta que estão no âmbito quando o seu código JavaScript é executado.

Nota: também pode usar o objeto abreviado response para aceder a estas propriedades a partir de um fluxo de respostas. O objeto response refere-se a context.proxyResponse ou context.targetResponse, consoante o ponto do fluxo em que o código JavaScript é executado.

context.*Response object properties

Nome de propriedade	Descrição
headers	Os cabeçalhos HTTP da mensagem de resposta como um mapeamento de String => List.
	Exemplo: var cookie = context.targetResponse.headers['Set-Cookie'];
status	O código de estado com a mensagem de estado como uma propriedade. O código de estado e a mensagem de estado estão disponíveis como propriedades.
	Exemplo: var status = context.targetResponse.status.code; // 200 var msg = context.targetResponse.status.message; // "OK"
content	O corpo HTTP (conteúdo da payload) da mensagem de resposta. O conteúdo da resposta tem os seguintes membros: context.targetResponse.content.asXML; context.targetResponse.content.asJSON;

Usar a notação .asXML

Existe uma forma prática de percorrer um documento XML através da notação .asXML. Esta secção descreve como usar esta notação e em que se diferencia de request.content e context.proxyRequest.content.

Por exemplo:

request.content.asXML

ou

context.proxyRequest.content.asXML

Ambos os formulários *.content e *.content.asXML podem ser usados num contexto de string, e o JavaScript vai forçá-los a tornarem-se strings. No primeiro caso (*.content), a string inclui todas as declarações, bem como comentários XML. No último caso (*.content.asXML), o valor da string do resultado é limpo de declarações e comentários.

Exemplo

msg.content:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>
<!-- mg023.mail.gq1.yahoo.com uncompressed/chunked Sat Dec 14 01:23:35 UTC 2013 -->

msg.content.asXML:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>

Além disso, pode usar o formulário .asXML para percorrer a hierarquia XML, especificando os nomes dos elementos e atributos. Não é possível percorrer a hierarquia usando a outra sintaxe.

Depure com declarações print() de JavaScript

Se estiver a usar a política de JavaScript para executar código JavaScript personalizado, tenha em atenção que 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. Por exemplo:

if (context.flow=="PROXY_REQ_FLOW") {
     print("In proxy request flow");
     var username = context.getVariable("request.queryparam.user");
     print("Got query param: " + username);
     context.setVariable("USER.name", username);
     print("Set query param: " + context.getVariable("USER.name"));
}


if (context.flow=="TARGET_REQ_FLOW") {
     print("In target request flow");
     var username = context.getVariable("USER.name");
     var url = "http://mocktarget.apigee.net/user?"
     context.setVariable("target.url", url + "user=" + username);
     print("Callout to URL: ", context.getVariable("target.url"));
}

Para ver o resultado, selecione Resultado de todas as transações na parte inferior da janela de depuração. Também pode encontrar o resultado na propriedade de depuração denominada stepExecution-stdout.

Fazer chamadas de JavaScript com httpClient

Use httpClient para fazer vários pedidos HTTP assíncronos e paralelos a qualquer URL a partir de código JavaScript personalizado executado num fluxo de proxy de API. O objeto httpClient é exposto pelo modelo de objeto JavaScript do Apigee.

Acerca de httpClient

O objeto httpClient é exposto ao código JavaScript personalizado executado no Apigee através do modelo de objeto JavaScript. Para anexar JavaScript personalizado a um proxy de API, use a política JavaScript. Quando a política é executada, o código JavaScript personalizado é executado.

O objeto httpClient é útil para desenvolver serviços compostos ou mashups. Por exemplo, pode consolidar várias chamadas de back-end num único método API.

Nota: 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 de API executando a política MessageLogging no PostClientFlow, que é executado depois de a resposta ter sido enviada de volta para o cliente.

Segue-se um padrão de utilização básico. Instancie um objeto Request, atribua-lhe um URL (por exemplo, a um serviço de back-end que quer chamar) e chame httpClient.send com esse objeto Request.

var myRequest = new Request();
myRequest.url = "http://www.example.com";
var exchangeObj = httpClient.send(myRequest);

Referência httpClient

O cliente HTTP expõe dois métodos: get() e send().

httpClient.get()

Um método prático para pedidos HTTP GET simples, sem suporte para cabeçalhos HTTP.

Utilização

var exchangeObj = httpClient.get(url);

Devoluções

O método devolve um objeto exchange. Este objeto não tem propriedades e expõe os seguintes métodos:

• isError(): (booleano) devolve true se o httpClient não conseguir estabelecer ligação ao servidor. Os códigos de estado HTTP 4xx e 5xx resultam em isError() false, uma vez que a ligação foi concluída e foi devolvido um código de resposta válido. Se isError() devolver true, uma chamada para getResponse() devolve o undefined JavaScript.
• isSuccess(): (Booleano) Devolve true se o envio tiver sido concluído e bem-sucedido.
• isComplete(): (Booleano) Devolve true se o pedido estiver concluído.
• waitForComplete(): pausa a discussão até que o pedido seja concluído (com êxito ou erro).
  Antipattern: a utilização de waitForComplete não é recomendada e é considerada um antipattern. Em alternativa, recomendamos que use callbacks. Para ver detalhes, consulte o artigo Antipattern: Use waitForComplete() in JavaScript code (Antipattern: use waitForComplete() no código JavaScript).
• getResponse(): (objeto) devolve o objeto de resposta se o httpClient.send() estiver concluído e tiver êxito. O objeto devolvido tem os métodos e as propriedades idênticos ao objeto context.proxyResponse. Consulte o resumo do objeto de contexto.
• getError(): (string) Se a chamada para httpClient.send() tiver resultado num erro, devolve a mensagem de erro como uma string.

Exemplo

Envie um objeto de pedido totalmente configurado que contenha as propriedades do pedido HTTP. Use uma chamada de retorno não bloqueadora para processar a resposta.

Nota: a utilização de callbacks para processar respostas de forma assíncrona é uma prática recomendada. A utilização da função waitForComplete() não é recomendada e é considerada um antipadrão. Veja também Antipattern: use waitForComplete() no código JavaScript.

// Add the required the headers for making a specific API request
var headers = {'X-SOME-HEADER' : 'some value' };
// Make a GET API request along with headers
var myRequest = new Request("http://www.example.com","GET",headers);

// Define the callback function and process the response from the GET API request
function onComplete(response,error) {
 // Check if the HTTP request was successful
    if (response) {
      context.setVariable('example.status', response.status);
     } else {
      context.setVariable('example.error', 'Woops: ' + error);
     }
}

// Specify the callback Function as an argument
httpClient.get(myRequest, onComplete);

Usar a política de JavaScript

Use a política de JavaScript para anexar código JavaScript personalizado a um fluxo de proxy. Consulte a Política de JavaScript.

Tópicos relacionados

• Política de JavaScript
• Modelo de objeto JavaScript
• Introdução aos antipadrões