Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
O que
Com a política de chamadas de serviço, é possível chamar outro serviço do seu fluxo de proxy de API. É possível fazer chamadas para um serviço externo, como um endpoint de serviço RESTful externo, ou para serviços internos, como um proxy de API na mesma organização e ambiente.
- Em um caso de uso externo, você faz uma chamada para uma API de terceiros externa ao seu proxy. A resposta da API de terceiros é analisada e inserida na mensagem de resposta da sua API, enriquecendo e "mascarando" os dados dos usuários finais do app. Também é possível fazer uma solicitação usando a política de chamada de serviço no fluxo de solicitação e passar as informações na resposta para o TargetEndpoint do proxy de API.
- Em outro caso de uso, chame um proxy que esteja na mesma organização e ambiente do qual você está chamando. Isso pode ser útil, por exemplo, quando você tem um proxy que oferece alguma funcionalidade discreta de baixo nível que um ou mais proxies consumirão. Por exemplo, um proxy que expõe operações de criação/leitura/atualização/exclusão com um armazenamento de dados de back-end pode ser o proxy de destino para vários outros proxies que expõem os dados aos clientes.
A política aceita solicitações por HTTP e HTTPS.
Amostras
Chamada local para um proxy interno
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Neste exemplo, é criada uma chamada para um proxy de API local (ou seja, na mesma organização e ambiente) denominada data-manager
, especificando o endpoint do proxy com o nome default
.
URL como uma variável
<HTTPTargetConnection> <URL>http://example.com/{request.myResourcePath}</URL> </HTTPTargetConnection>
Este exemplo usa uma variável no URL para preencher dinamicamente o URL do destino. A parte de protocolo do URL, http://, não pode ser especificada por uma variável. Além disso, use variáveis separadas para a parte do domínio do URL e para o restante do URL.
Solicitação de geocodificação/definição do Google
<ServiceCallout name="ServiceCallout-GeocodingRequest1"> <DisplayName>Inline request message</DisplayName> <Request variable="authenticationRequest"> <Set> <QueryParams> <QueryParam name="address">{request.queryparam.postalcode}</QueryParam> <QueryParam name="region">{request.queryparam.country}</QueryParam> <QueryParam name="sensor">false</QueryParam> </QueryParams> </Set> </Request> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
http://maps.googleapis.com/maps/api/geocode/json
Em vez de usar uma política, como "Atribuir mensagem" para criar o objeto de solicitação, você pode defini-lo diretamente na política de chamada de serviço. Neste exemplo, a política de chamada de serviço define os valores de três parâmetros de consulta passados para o serviço externo. É possível criar uma mensagem de solicitação inteira na política de chamada de serviço que especifica um payload, um tipo de codificação, como application/xml, cabeçalhos, parâmetros de formulário etc.
Veja outro exemplo em que a solicitação é formada antes de alcançar a política de chamada de serviço.
<ServiceCallout name="ServiceCallout-GeocodingRequest2"> <Request clearPayload="false" variable="GeocodingRequest"/> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
O conteúdo da mensagem de solicitação é extraído de uma variável chamada GeocodingRequest, que pode ser preenchida, por exemplo, por uma política "AssignMessage". A mensagem de resposta é atribuída à variável chamada GeocodingResponse, em que fica disponível para ser analisada por uma política de variáveis de extração ou por código personalizado escrito em JavaScript ou Java. A política aguarda 30 segundos para a resposta da API Google Geocoding antes de expirar.
Para ver um exemplo completo de proxy de API que usa esse exemplo de chamada de serviço com as políticas de atribuição de mensagem e de extração de variáveis, consulte Como usar a composição de políticas.
Chamar servidores de destino
<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout"> <DisplayName>service-callout</DisplayName> <Properties/> <Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request> <Response>myResponse</Response> <HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection> </ServiceCallout>
Esta política usa o atributo LoadBalancer para chamar os servidores de destino e fazer o balanceamento de carga entre eles. Neste exemplo, a carga é distribuída por dois servidores de destino, chamados "httpbin" e "yahoo". Consulte Balanceamento de carga entre servidores de back-end para mais informações sobre como configurar servidores de destino para o proxy e como configurar o balanceamento de carga.
Sobre a política de chamada de serviço
Há muitos cenários em que é possível usar uma política de chamada de serviço no proxy de API. Por exemplo, você pode configurar um proxy de API para fazer chamadas a um serviço externo para fornecer dados de geolocalização, avaliações de clientes, itens do catálogo de varejo de um parceiro e assim por diante.
Geralmente, uma chamada é usada com duas outras políticas: "Atribuir mensagem" e "Extrair variáveis".
- Solicitação: a opção "Atribuir mensagem" preenche a mensagem de solicitação enviada ao serviço remoto.
-
Resposta: "Extrair variáveis" analisa a resposta e extrai o conteúdo específico.
A composição comum da política de chamada de serviço envolve:
- Política de atribuição de mensagem: cria uma mensagem de solicitação, preenche os cabeçalhos HTTP, os parâmetros de consulta, define o verbo HTTP etc.
- Política de chamada de serviço: refere-se a uma mensagem criada pela política de atribuição de mensagem, define um URL de destino para a chamada externa e define um nome para o objeto de resposta retornado pelo serviço de destino.
Para melhorar o desempenho, você também pode armazenar em cache as respostas da chamada de serviço, conforme descrito nesta conversa da comunidade da Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html. - Política de extração de variáveis: normalmente, define uma expressão JSONPath ou XPath que analisa a mensagem gerada pela chamada de serviço. Em seguida, a política define as variáveis que contêm os valores analisados da resposta da chamada de serviço.
Consulte Como usar a composição de políticas para ver um exemplo completo de proxy de API que usa a política de chamada de serviço com as políticas "Atribuir mensagem" e "Extrair variáveis".
Como resolver erros personalizados
Referência de elemento
Veja a seguir elementos e atributos que podem ser configurados com esta política:
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1"> <DisplayName>Custom label used in UI</DisplayName> <Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request> <Response>calloutResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection> <LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection> </ServiceCallout>
Atributos <ServiceCallout>
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
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 |
falso | Opcional |
enabled |
Defina como Defina como |
true | Opcional |
async |
Esse atributo está obsoleto. |
falso | Obsoleto |
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 <Request>
Especifica a variável que contém a mensagem de solicitação enviada do proxy de API para o outro serviço. A variável pode ser criada por uma política anterior no fluxo, ou você pode criá-la inline na política de chamada de serviço.
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request>
A sintaxe das tags <Remove>, <Copy>, <Add> e <Set> é a mesma que a da política "Atribuir mensagem".
A política retornará um erro se a mensagem de solicitação não puder ser resolvida ou for de um tipo de mensagem de solicitação inválido.
No exemplo mais simples, você transmite uma variável contendo a mensagem de solicitação que foi preenchida anteriormente no fluxo do proxy de API:
<Request clearPayload="true" variable="myRequest"/>
Também é possível preencher a mensagem de solicitação enviada ao serviço externo na própria política de chamada de serviço:
<Request> <Set> <Headers> <Header name="Accept">application/json</Header> </Headers> <Verb>POST</Verb> <Payload contentType="application/json">{"message":"my test message"}</Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
Padrão | Se você omitir o elemento da solicitação ou qualquer um dos atributos dele, o Edge atribuirá o
seguintes valores padrão:
<Request clearPayload="true" variable="servicecallout.request"/> Vejamos o que esses valores padrão significam. Primeiro,
É importante saber sobre esse nome padrão se você estiver usando mascaramento de dados. Se você omitir o nome da variável, será necessário adicionar
|
Presença | Opcional. |
Tipo | N/A |
Atributos
Atributo | Descrição | Padrão | Presença |
---|---|---|---|
variável |
Nome da variável que conterá a mensagem de solicitação. |
servicecallout.request |
Opcional |
clearPayload |
Se Defina a opção clearPayload como "false" somente se a mensagem de solicitação for necessária depois que a chamada de serviço for executada. |
true | Opcional |
Elemento <Request>/<IgnoreUnresolvedVariables>
Quando definido como true, a política ignora qualquer erro de variável não resolvido na solicitação.
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
Padrão | falso |
Presença | Opcional |
Tipo | Booleanos |
Elemento <Response>
Inclua esse elemento quando a lógica do proxy de API requer a resposta da chamada remota para processamento adicional.
Quando esse elemento está presente, ele especifica o nome da variável que conterá a mensagem de resposta recebida do serviço externo. A resposta do destino é atribuída à variável somente quando a resposta inteira é lida pela política. Se a chamada remota falhar por qualquer motivo, a política retornará um erro.
Se esse elemento for omitido, o proxy de API não aguardará a resposta. A execução do fluxo do proxy de API continua com todas as etapas subsequentes do fluxo. Além disso, para declarar o óbvio, sem um elemento Response
, a resposta do destino não está disponível para processamento nas etapas subsequentes e não há como o fluxo de proxy detectar uma falha na chamada remota.
Um uso comum para omitir o elemento Response
ao usar ServiceCallout é registrar as mensagens em um sistema externo.
<Response>calloutResponse</Response>
Padrão | NA |
Presença | Opcional |
Tipo | String |
Elemento <Timeout>
O tempo em milésimos de segundo em que a política de chamada de serviço aguardará uma resposta do destino. Não é possível definir esse valor dinamicamente no ambiente de execução. Se a chamada de serviço atingir um tempo limite, um HTTP 500 será retornado, a política falhará e o proxy de API entrará em um estado de erro, conforme descrito em Como solucionar falhas.
<Timeout>30000</Timeout>
Padrão | 55.000 milissegundos (55 segundos), a configuração de tempo limite de HTTP padrão para a Apigee Borda |
Presença | Opcional |
Tipo | Inteiro |
Elemento <HTTPTargetConnection>
Fornece detalhes de transporte, como propriedades URL, TLS/SSL e HTTP. Consulte a referência de configuração do <TargetEndpoint>
.
<HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection>
Padrão | N/A |
Presença | Obrigatório |
Tipo | N/D |
Elemento <HTTPTargetConnection>/<URL>
O URL do serviço que está sendo chamado:
<HTTPTargetConnection> <URL>http://example.com</URL> </HTTPTargetConnection>
Você pode fornecer parte do URL dinamicamente com uma variável. No entanto, a parte de protocolo do URL, http:// abaixo, não pode ser especificada por uma variável. No próximo exemplo, você usa uma variável para especificar o valor de um parâmetro de consulta:
<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>
Se preferir, defina uma parte do caminho do URL com uma variável:
<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>
Se você quiser usar uma variável para especificar o domínio e a porta do URL, use uma variável somente para o domínio e a porta e uma segunda variável para qualquer outra parte do URL:
<URL>http://{request.dom_port}/{request.resourcePath}</URL>
Padrão | N/A |
Presença | Obrigatório |
Tipo | String |
Elemento <HTTPTargetConnection>/<SSLInfo>
A configuração de TLS/SSL para o serviço de back-end. Para receber ajuda com a configuração TLS/SSL, consulte Como configurar o TLS da Borda para o back-end (Cloud e Nuvem Privada) e "TLS/SSL TargetEndpoint Configuration" na referência de configuração de proxy de API.
<HTTPTargetConnection> <URL>https://example.com</URL> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>ref://mykeystoreref</KeyStore> ## Use of a reference is recommended <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> <Ciphers/> <Protocols/> </SSLInfo> </HTTPTargetConnection>
Padrão | N/A |
Presença | Opcional |
Tipo | N/A |
Elemento <HTTPTargetConnection>/<Properties>
Propriedades de transporte HTTP para o serviço de back-end. Para mais informações, consulte a Referência das propriedades de endpoint.
<HTTPTargetConnection> <URL>http://example.com</URL> <Properties> <Property name="allow.http10">true</Property> <Property name="request.retain.headers"> User-Agent,Referer,Accept-Language </Property> </Properties> </HTTPTargetConnection>
Padrão | N/A |
Presença | Opcional |
Tipo | N/A |
Elemento <HTTPTargetConnection>/<LoadBalancer>
Chame um ou mais servidores de destino e faça o balanceamento de carga neles. Veja o exemplo de Servidores de destino de chamada na seção "Amostras". Consulte também Balanceamento de carga entre servidores de back-end. Veja também esta postagem na comunidade que discute maneiras de chamar servidores de destino com base na política de chamada de serviço e como usar regras de rota.
<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Padrão | N/A |
Presença | Opcional |
Tipo | N/A |
Elemento <LocalTargetConnection>
Especifica um proxy local, ou seja, um proxy na mesma organização e ambiente, como o destino das chamadas de serviço.
Para especificar o destino em mais detalhes, use os elementos <APIProxy>
e <ProxyEndpoint>
ou o elemento <Path>
.
<LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection>
Padrão | N/A |
Presença | Obrigatório |
Tipo | N/A |
Elemento <LocalTargetConnection>/<APIProxy>
O nome de um proxy de API que é o destino de uma chamada local. O proxy precisa estar na mesma organização e ambiente que o proxy que está fazendo a chamada.
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Junto com o elemento <APIProxy>
, inclua o elemento <ProxyEndpoint>
para especificar o nome do endpoint de proxy que precisa ser direcionado para a chamada.
<LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> </LocalTargetConnection>
Padrão | N/A |
Presença | Obrigatório |
Tipo | String |
Elemento <LocalTargetConnection>/<ProxyEndpoint>
O nome do endpoint do proxy que precisa ser o destino das chamadas. Esse é um endpoint de proxy no proxy de API especificado com o elemento <APIProxy>
.
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Padrão | N/A |
Presença | Opcional |
Tipo | N/A |
Elemento <LocalTargetConnection>/<Path>
Um caminho para o endpoint que está sendo direcionado. O endpoint precisa se referir a um proxy na mesma organização e ambiente que o proxy que está fazendo a chamada.
Use-o em vez de um par <APIProxy>/<ProxyEndpoint>
quando você não souber o nome do proxy, ou não puder confiar nele. O caminho pode ser um destino confiável.
<LocalTargetConnection> <Path>/data-manager</Path> </LocalTargetConnection>
Padrão | N/A |
Presença | Opcional |
Tipo | N/A |
Esquemas
Variáveis de fluxo
As variáveis de fluxo permitem o comportamento dinâmico de políticas e fluxos no ambiente de execução, com base em cabeçalhos HTTP, conteúdo de mensagens ou contexto de fluxo. As variáveis de fluxo predefinidas a seguir estarão disponíveis depois que uma política de chamada de serviço for executada. Para mais informações sobre as variáveis de fluxo, consulte a Referência de variáveis.
As chamadas de serviço têm uma solicitação e uma resposta próprias, e é possível acessar esses dados por meio de variáveis. Como a mensagem principal está usando os prefixos de variável request.*
e response.*
, use os prefixos myrequest.*
e calloutResponse.*
(os padrões na configuração da chamada de serviço) para acessar os dados da mensagem específicos da chamada de serviço. O primeiro exemplo na tabela a seguir mostra como você recebe os cabeçalhos HTTP na chamada de serviço.
Variável | Descrição |
---|---|
Veja abaixo um exemplo de como conseguir os cabeçalhos de solicitação e de chamada de serviço da mesma forma como você faz com os cabeçalhos da solicitação principal e da resposta.
em que calloutResponse é o nome da variável da resposta na chamada de serviço, e myRequest é o nome da variável da solicitação. Exemplo:
retorna o cabeçalho Content-Length da resposta da chamada de serviço. |
Escopo: com base no encaminhamento da chamada de serviço Um cabeçalho de mensagem na solicitação ou resposta de chamada de serviço. Por exemplo, se o destino do proxy de API for http://example.com e o destino da chamada de serviço for http://mocktarget.apigee.net, essas variáveis serão os cabeçalhos da chamada para http://mocktarget.apigee.net. |
servicecallout.requesturi |
Escopo: com base no encaminhamento da solicitação de chamada de serviço O URI TargetEndpoint de uma política ServiceCallout. O URI é o URL TargetEndpoint sem a especificação do protocolo e do domínio. |
servicecallout.{policy-name}.target.url |
Escopo: com base no encaminhamento da solicitação de chamada de serviço O URL de destino de uma chamada de serviço. |
em que |
Escopo: com base no encaminhamento da resposta da chamada de serviço O corpo da resposta da chamada de serviço. |
servicecallout.{policy-name}.expectedcn |
Escopo: com base no encaminhamento da solicitação de chamada de serviço O nome comum esperado do TargetEndpoint, conforme mencionado em uma política ServiceCallout. Isso é significativo somente quando o TargetEndpoint se refere a um endpoint TLS/SSL. |
servicecallout.{policy-name}.failed |
Escopo: com base no encaminhamento da resposta da chamada de serviço Booleano que indica se a política foi concluída, é falsa ou falhou. |
Erros
Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. 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.
Código de falha | Status HTTP | Causa | Correção |
---|---|---|---|
steps.servicecallout.ExecutionFailed |
500 |
Esse erro pode ocorrer quando:
|
build |
steps.servicecallout.RequestVariableNotMessageType |
500 | A variável "Request" especificada na política não é do tipo "Message". Por exemplo, no caso de uma string ou outro tipo de mensagem que não é uma mensagem, você vê esse erro. | build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 | A variável "Request" especificada na política não é do tipo "Request Message". Por exemplo, se for um tipo de resposta, você verá esse erro. | build |
Erros na implantação
Esses erros podem ocorrer quando você implanta um proxy que contém essa política.
Nome do erro | Causa | Corrigir |
---|---|---|
URLMissing |
O elemento <URL> dentro de <HTTPTargetConnection> está ausente ou vazio. |
build |
ConnectionInfoMissing |
Esse erro ocorrerá se a política não tiver um elemento <HTTPTargetConnection> ou <LocalTargetConnection> . |
build |
InvalidTimeoutValue |
Este erro ocorrerá se o valor <Timeout> for negativo ou zero. |
build |
Variáveis de falha
Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.
Variáveis | Onde | Exemplo |
---|---|---|
fault.name="fault_name" |
fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. | fault.name = "RequestVariableNotMessageType" |
servicecallout.policy_name.failed |
policy_name é o nome especificado pelo usuário da política que causou a falha. | servicecallout.SC-GetUserData.failed = true |
Exemplo de resposta de erro
{ "fault":{ "detail":{ "errorcode":"steps.servicecallout.RequestVariableNotMessageType" }, "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: request variable data_str value is not of type Message" } }
Exemplo de regra de falha
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType"> <Step> <Name>AM-RequestVariableNotMessageType</Name> </Step> <Condition>(fault.name = "RequestVariableNotMessageType")</Condition> </FaultRule>
Temas relacionados
- Gerar ou modificar mensagens: Política de atribuição de mensagem
- Extrair variáveis: Política de extração de variáveis
- Variáveis: Referência de variáveis
- Configuração de TLS/SSL
- Como configurar TLS da borda para o back-end (Cloud e nuvem privada)
- "Configuração do TargetEndpoint de TLS/SSL" na Referência de configuração de proxy de API
- Propriedades de transporte HTTP: Referência das propriedades de endpoint
- Alternativa à frase de destaque de serviço: HTTPClient escrito em JavaScript. Consulte Modelo de objeto JavaScript