Política de ExtensionFrase

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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

Uma extensão fornece acesso a um recurso específico externo ao Apigee Edge. O recurso pode ser serviços do Google Cloud Platform, como o Cloud Storage ou o Cloud Speech-to-Text. No entanto, ele 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: como adicionar e usar uma extensão.

Antes de acessar uma extensão da política Extensionframe, você precisa adicionar, configurar e implantar a extensão a partir de um pacote de extensões que já esteja 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 Tutorial: como usar extensões para um tutorial completo usando a extensão Cloud Logging.

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

Sobre a política ExtensionChamada

Use a política Extension callout quando você quiser usar uma extensão configurada para acessar um recurso externo de um proxy de API.

Antes de usar essa política, você precisará do seguinte:

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

Como usar a política Extension callout em um PostClientFlow

Você pode invocar a política Extension callout 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 a 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 Extension callout para chamar a extensão do Google Cloud Logging de um PostClientFlow, verifique se a sinalização features.allowExtensionsInPostClientFlow está definido como true na sua organização.

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

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

Todas as restrições sobre chamar a política MessageLogging do PostClientFlow também se aplicam à política ExtensionCall. Consulte as 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>

<ConnectorCallout> atributos

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

&lt;Action&gt; elemento

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

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

Cada extensão expõe o próprio conjunto de ações que fornecem acesso à funcionalidade do recurso que a extensão representa. Pense em uma ação como uma função chamada 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 nesta política.

<Conector> elemento

O nome da extensão configurada a ser usada. Esse é o nome com escopo do ambiente que a extensão recebeu quando 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ões. Esses valores de configuração podem representar diferenças importantes na funcionalidade do ambiente de execução entre extensões configuradas no mesmo pacote. Portanto, especifique a extensão correta a ser invocada.

&lt;Input&gt; elemento

JSON contendo o corpo da solicitação a ser enviada à extensão.

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

Essencialmente, esse é 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 mais detalhes sobre as propriedades de cada ação.

Embora muitos valores de elementos <Input> funcionem corretamente sem estar 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, inclua o JSON como uma seção CDATA para evitar erros de análise no ambiente de execução.

O valor do elemento <Input> é um JSON bem formado com propriedades que especificam valores para enviar à ação de extensão a ser invocada. Por exemplo, o Extensão do Google Cloud Logging a ação log da extensão usa valores que especificam o registro no qual gravar (logName), metadados a serem incluídos com a entrada (metadata) e a mensagem de registro (data). Aqui está 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 no 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 ambiente de execução pelo valor da variável referenciada.

Por exemplo, é possível reescrever o bloco <Input> anterior para usar a variável de fluxo client.ip e conseguir o endereço IP do cliente que está chamando o proxy de API:

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

Se você pretende que um valor de propriedade no JSON seja colocado entre aspas no tempo de execução, use aspas no código JSON. Isso é válido mesmo quando você especifica uma variável de fluxo como um valor de propriedade JSON a ser resolvido no ambiente 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>

No ambiente de execução, os valores da propriedade 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 o próprio JSON que representa um objeto.
• Valor da propriedade message: o valor da variável de fluxo client.ip com aspas.

&lt;Output&gt; elemento

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, onde você pode acessá-lo a partir de outro código de proxy da API.

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

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

&lt;Output&gt; Atributos

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.