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 comotrue
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
comotrue
.
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 Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
false | Opcional |
enabled |
Defina como Defina como |
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 |
---|---|
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 stringexample-log
. - Valor da propriedade
metadata
: o valor da variável de fluxomy.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 fluxoclient.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 comoextensionOutput
, 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. |
build |
ConnectorInstanceDoesNotExists |
A extensão especificada no elemento <Connector> não existe no ambiente. |
build |
InvalidAction |
O elemento <Action> na política ExtensionCallout está ausente ou definido com um valor vazio. |
build |
AllowExtensionsInPostClientFlow |
É proibido ter a política ExtensionCallout em um fluxo PostClient. | build |