Política de ExtensionFrase

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Use a política ExtensionCallout para incorporar uma extensão a um proxy de API.

Uma extensão dá acesso a um recurso específico externo ao Apigee Edge. O recurso pode ser um serviço do Google Cloud Platform, como o Cloud Storage ou o Cloud Speech-to-Text. No entanto, o recurso pode ser qualquer recurso externo acessível por HTTP ou HTTPS.

Para uma visão geral das extensões, consulte O que são extensões? Para um tutorial introdutório, consulte Tutorial: adicionar e usar uma extensão.

Antes de acessar uma extensão da política ExtensionCallout, é necessário adicionar, configurar e implantar a extensão de um pacote já instalado na sua organização do Apigee Edge.

Amostras

Confira abaixo um exemplo de política para uso com a extensão do Cloud Logging:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Consulte o Tutorial: como usar extensões para um tutorial completo usando a extensão do Cloud Logging.

Para exemplos de todas as extensões disponíveis, consulte Visão geral da referência de extensões.

Sobre a política ExtensionCallout

Use a política ExtensionCallout quando quiser usar uma extensão configurada para acessar um recurso externo de dentro de um proxy de API.

Antes de usar esta política, você precisa:

• Alguns detalhes sobre o recurso externo que você quer acessar com essa política. Esses detalhes são específicos do recurso. Por exemplo, se a política acessar seu banco de dados do Cloud Firestore, você precisará saber o nome da coleção e do documento que quer criar ou acessar. Normalmente, você usa informações específicas do recurso ao configurar o processamento de solicitações e respostas dessa política.
• Uma extensão adicionada, configurada e implantada no ambiente em que o proxy de API será implantado. Em outras palavras, se você usar essa política para acessar um serviço específico do Google Cloud, uma extensão implantada para esse serviço precisará existir no seu ambiente. Os detalhes da configuração geralmente incluem informações necessárias para restringir o acesso ao recurso, como um ID do projeto ou um nome de conta.

Como usar a política ExtensionCallout em um PostClientFlow

É possível invocar a política ExtensionCallout do PostClientFlow de um proxy de API. O PostClientFlow é executado depois que a resposta é enviada ao cliente solicitante, o que garante que todas as métricas estejam disponíveis para geração de registros. Para detalhes sobre como usar o PostClientFlow, consulte a Referência de configuração de proxy da API.

Se você quiser usar a política ExtensionCallout para chamar a extensão do Google Cloud Logging de um PostClientFlow, verifique se a flag features.allowExtensionsInPostClientFlow está definida como true na sua organização.

• Se você for cliente do Apigee Edge para nuvem pública, a sinalização features.allowExtensionsInPostClientFlow será definida como true por padrão.

• Se você for cliente do Apigee Edge para nuvem privada, use a API Atualizar propriedades da organização para definir a flag features.allowExtensionsInPostClientFlow como true.

Todas as restrições de chamada da política MessageLogging do PostClientFlow também se aplicam à política ExtensionCallout. Consulte Observações sobre o uso para mais informações.

Referência de elemento

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

Atributos <ConnectorCallout>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

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

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Elemento <Action>

A ação exposta pela extensão que a política precisa invocar.

<Action>action-exposed-by-extension</Action>

Cada extensão expõe um conjunto próprio de ações que fornecem acesso à funcionalidade do recurso que ela representa. Você pode pensar em uma ação como uma função que você chama com essa política, usando o conteúdo do elemento <Input> para especificar os argumentos da função. A resposta da ação é armazenada na variável especificada com o elemento <Output>.

Para uma lista das funções da extensão, consulte a referência da extensão que você está chamando dessa política.

Elemento <Connector>

O nome da extensão configurada a ser usada. É o nome no escopo do ambiente dado à extensão quando ela foi configurada para implantação em um ambiente.

<Connector>name-of-configured-extension</Connector>

Uma extensão tem valores de configuração que podem ser diferentes de outra extensão implantada com base no mesmo pacote de extensão. Esses valores de configuração podem representar diferenças importantes na funcionalidade de tempo de execução entre extensões configuradas do mesmo pacote. Portanto, especifique a extensão correta a ser invocada.

Elemento <Input>

JSON que contém o corpo da solicitação a ser enviado para a extensão.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Esse é essencialmente um argumento para a ação especificada com o elemento <Action>. O valor do elemento <Input> varia de acordo com a extensão e a ação que você está invocando. Consulte a documentação do pacote de extensão para detalhes sobre as propriedades de cada ação.

Embora muitos valores de elementos <Input> funcionem corretamente sem serem incluídos como uma seção <![CDATA[]]>, as regras do JSON permitem valores que não serão analisados como XML. Como prática recomendada, coloque o JSON em uma seção CDATA para evitar erros de análise de tempo de execução.

O valor do elemento <Input> é um JSON bem formado cujas propriedades especificam valores a serem enviados para a ação de extensão a ser invocada. Por exemplo, a ação log da extensão do Google Cloud Logging usa valores que especificam o registro em que gravar (logName), os metadados a serem incluídos na entrada (metadata) e a mensagem de registro (data). Confira um exemplo:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Como usar variáveis de fluxo em JSON <Input>

O conteúdo de <Input> é tratado como um modelo de mensagem. Isso significa que um nome de variável entre chaves será substituído no tempo de execução pelo valor da variável referenciada.

Por exemplo, você pode reescrever o bloco <Input> anterior para usar a variável de fluxo client.ip e receber o endereço IP do cliente que chama o proxy de API:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Se você quiser que um valor de propriedade no JSON seja colocado entre aspas no tempo de execução, use aspas no código JSON. Isso é verdade mesmo quando você especifica uma variável de fluxo como um valor de propriedade JSON a ser resolvido no tempo de execução.

O exemplo de <Input> a seguir inclui duas referências de variáveis de fluxo:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

Em tempo de execução, os valores das propriedades JSON serão resolvidos da seguinte maneira:

• Valor da propriedade logName: o literal de string example-log.
• Valor da propriedade metadata: o valor da variável de fluxo my.log.entry.metadata sem aspas. Isso pode ser útil se o valor da variável for um JSON que representa um objeto.
• Valor da propriedade message: o valor da variável de fluxo client.ip com aspas delimitadoras.

Elemento <Output>

Nome de uma variável que armazena a resposta da ação de extensão.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

ou

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Quando a resposta é recebida, o valor da resposta é colocado na variável especificada aqui, em que é possível acessá-lo de outro código de proxy de API.

Os objetos de resposta da extensão estão no formato JSON. Há duas opções para como a política processa o JSON:

• Analisada (padrão): a política analisa o objeto JSON e gera automaticamente variáveis com os dados JSON. Por exemplo, se o JSON contiver "messageId" : 12345; e você nomear a variável de saída como extensionOutput, poderá acessar esse ID de mensagem em outras políticas usando a variável {extensionOutput.messageId}.
• Não analisada: a variável de saída contém a resposta JSON bruta e não analisada da extensão. Se quiser, ainda é possível analisar o valor da resposta em uma etapa separada usando a política de JavaScript.

Atributos <Output>

Variáveis de fluxo

Nenhum.

Códigos de erro

Os erros retornados das políticas do Apigee Edge seguem um formato consistente, conforme descrito na Referência de erros de política.

Esta seção descreve as mensagens de erro e as variáveis de fluxo definidas quando esta política aciona um erro. Essa informação é importante para saber se você está desenvolvendo regras de falha para um proxy. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Erros de implantação

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