Política de ExtensionFrase

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

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

Uma extensão fornece acesso a um recurso específico fora do Apigee Edge. O recurso pode ser serviços do Google Cloud Platform, como o Cloud Storage ou o Cloud Speech-to-Text. Mas 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 conferir um tutorial de apresentação, consulte Tutorial: como adicionar e usar uma extensão.

Antes de acessar uma extensão da política Extension callout, você precisa adicionar, configurar e implantar a extensão de um pacote que já esteja instalado na sua organização do Apigee Edge.

Exemplos

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 do Cloud Logging.

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

Sobre a política Extension callout

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

Antes de usar essa política, você vai 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, você precisará saber a coleção e o nome do documento que quer criar ou acessar. Normalmente, você usa informações específicas do recurso na configuração do processamento de solicitações e respostas dessa política.
  • Uma extensão adicionada, configurada e implantada no ambiente em que seu 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, uma extensão implantada para esse serviço precisará existir no seu ambiente. Os detalhes de configuração geralmente incluem informações necessárias para restringir o acesso ao recurso, como um ID do projeto ou nome de 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 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 ExtensionPor para chamar a extensão do Google Cloud Logging de um PostClientFlow, verifique se a sinalização features.allowExtensionsInPostClientFlow está definida como true na sua organização.

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

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

Todas as restrições à chamada da política MessageLogging do PostClientFlow também se aplicam à política Extension callout. 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>

Atributos de <Connector callout>

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

Atributo Descrição Padrão Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

false Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

verdadeiro Opcional
async

Esse atributo está obsoleto.

false Descontinuado

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>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presença Opcional
Tipo String

Elemento <Action>

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

<Action>action-exposed-by-extension</Action>
Padrão Nenhum
Presença Obrigatório
Tipo String

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 que é 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 ver uma lista das funções da extensão, consulte a referência da extensão que você está chamando com base nessa política.

Elemento <Connector>

O nome da extensão configurada a ser usada. Este é o nome com escopo do ambiente que recebeu a extensão quando ela foi configurada para implantação em um ambiente.

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

Padrão Nenhum
Presença Obrigatório
Tipo String

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 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 enviada para a extensão.

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

Padrão Nenhum
Presença Opcional ou obrigatório, dependendo da extensão.
Tipo String

Ele é essencialmente um argumento para a ação que você especifica 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ões para ver detalhes sobre as propriedades de cada ação.

Muitos valores do elemento <Input> vão funcionar corretamente sem serem incluídos em uma seção <![CDATA[]]>, mas as regras do JSON permitem valores que não vão ser analisados como XML. Como prática recomendada, inclua o JSON como uma seção CDATA para evitar erros de análise no momento da execução.

O valor do elemento <Input> é um JSON bem formado, cujas propriedades especificam valores a serem enviados à ação da extensão para invocar. Por exemplo, a ação log da extensão Google Cloud Logging Extension aceita valores que especificam o registro a ser gravado (logName), os metadados a serem incluídos na entrada (metadata) e a mensagem de registro (data). Veja 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 o nome de uma variável entre chaves será substituído pelo valor da variável referenciada no momento da execução.

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 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 fique entre aspas durante a 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 entre 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.

Elemento <Output>

Nome de uma variável que armazena a resposta da ação da 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 -->

Padrão Nenhum
Presença Opcional ou obrigatório, dependendo da extensão.
Tipo Objeto ou string analisado, dependendo da configuração do atributo parsed.

Quando a resposta é recebida, o valor da resposta é colocado na variável que você especifica aqui, onde pode ser acessado de outro código proxy da API.

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

  • Analisada (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 a variável de saída como extensionOutput, será possível 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 você quiser, ainda é possível analisar o valor da resposta em uma etapa separada usando a política JavaScript.

Atributos de <Saída>

Atributo Descrição Padrão Presença
parsed Analisa o objeto JSON retornado da extensão, o que permite que os dados no objeto JSON sejam acessados como variáveis por outras políticas. verdadeiro Opcional

Variáveis de fluxo

Nenhum.

Códigos de erro

Os erros retornados das políticas do Apigee Edge seguem um formato consistente, conforme descrito em 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.

Nome do erro Status HTTP Causa
ExecutionFailed 500 A extensão responde com um erro.

Erros de implantação

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

Erro de nome Ocorre quando Corrigir
InvalidConnectorInstance O elemento <Connector> está vazio.
ConnectorInstanceDoesNotExists A extensão especificada no elemento <Connector> não existe no ambiente.
InvalidAction O elemento <Action> na política ExtensionCallout está ausente ou definido com um valor vazio.
AllowExtensionsInPostClientFlow É proibido ter a política ExtensionCallout em um fluxo PostClient.