Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
Il criterio ExternalCallout consente di inviare richieste gRPC al server gRPC per implementare un comportamento personalizzato non supportato dai criteri di Apigee. Nel codice del tuo server, puoi accedere facilmente alle variabili di flusso e modificarle all'interno del flusso di un proxy.
Apigee comunica con un server gRPC tramite un criterio ExternalCallout tramite un'API. Apigee utilizza l'API per inviare le variabili di flusso al server gRPC. All'interno del server gRPC, puoi leggere e, a seconda della variabile, modificare le variabili di flusso elencate nella pagina di riferimento Variabili di flusso, nonché altre variabili specificate nel codice XML del criterio.
Se configuri il server gRPC con Apigee e includi questo criterio in un proxy, Apigee gestirà le richieste API come segue:
- Apigee invia un messaggio contenente le variabili di flusso al server gRPC.
- Il codice del server gRPC viene eseguito, accedendo alle variabili come definite nel codice e modificandole. Il server gRPC invia quindi una risposta contenente tutte le variabili di flusso ad Apigee.
- Apigee legge la risposta dal tuo server gRPC. Se vengono aggiunte variabili o se vengono modificate variabili di flusso modificabili, queste vengono aggiornate in Apigee.
Questo è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di criteri.
Per scoprire di più sull'invio di richieste gRPC, consulta i seguenti link:
<ExternalCallout>
Definisce un criterio ExternalCallout.
<ExternalCallout async="true" continueOnError="true" enabled="true" name="EC">
Questo elemento ha i seguenti attributi comuni a tutti i criteri:
Attributo | Predefinito | Obbligatorio? | Descrizione |
---|---|---|---|
name |
N/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per
la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche:
|
enabled |
true | Facoltativo | Imposta su true per applicare il criterio. Imposta su false per disattivare il
criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso. |
async |
falso | Deprecato | Questo attributo è stato ritirato. |
La tabella seguente descrive gli elementi secondari di
<ExternalCallout>
.
Elemento secondario | Obbligatorio | Descrizione |
---|---|---|
<TimeoutMs> |
Obbligatorio | Il timeout in millisecondi per le richieste gRPC. |
<GrpcConnection> |
Obbligatorio | Specifica il nome di un elemento TargetServer esistente che deve essere il server gRPC a cui inviare le richieste.
|
<Configurations> |
Facoltativo | Consente di configurare vari aspetti del criterio ExternalCallout, inclusi gli elementi <Property> e <FlowVariable> . |
Esempio 1
Gli esempi pratici di ExternalCallout sono disponibili nella sezione External Callout Samples (Esempi di callout esterni) su GitHub.
L'esempio seguente illustra la configurazione di un criterio ExternalCallout.
<ExternalCallout enabled="true" continueOnError="false" name="ExternalCallout-1"> <DisplayName>External Callout 1</DisplayName> <TimeoutMs>5000</TimeoutMs> <GrpcConnection> <Server name="external-target-server"/> </GrpcConnection> <Configurations> <Property name="with.request.content">true</Property> <Property name="with.request.headers">false</Property> <Property name="with.response.content">true</Property> <Property name="with.response.headers">false</Property> <FlowVariable>example1.flow.variable</FlowVariable> <FlowVariable>example2.flow.variable</FlowVariable> </Configurations> <ExternalCallout>
L'esempio invia una richiesta a un server gRPC esterno rappresentato dal
TargetServer denominato external-target-server
, con le seguenti configurazioni:
<Property>
: nella richiesta inviata al server gRPC vengono inclusi i contenuti della richiesta e della risposta, ma non le intestazioni della richiesta e della risposta.<FlowVariable>
: includi ulteriori variabili di flussoexample1.flow.variable
eexample2.flow.variable
, specificate dagli elementiFlowVariable
, nella richiesta inviata al server gRPC.
Esempio 2
Nell'esempio seguente, l'attributo useTargetUrl
dell'elemento Audience
è impostato su true
. Quando useTargetUrl
è true
,
il nome host del server gRPC di destinazione viene utilizzato come pubblico. Ad
esempio, se l'host del server è my-grpc-server-java.a.run.app
, il segmento di pubblico
utilizzato sarà https://my-grpc-server-java.a.run.app
.
<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1"> <DisplayName>External-Callout-1</DisplayName> <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <GoogleIDToken> <Audience useTargetUrl="true"/> </GoogleIDToken> </Authentication> </GrpcConnection> <TimeoutMs>5000</TimeoutMs> <Configurations> <Property name="with.request.content">true</Property> <Property name="with.request.headers">true</Property> <Property name="with.response.content">true</Property> <Property name="with.response.headers">true</Property> <FlowVariable>example.flow.variable</FlowVariable> <FlowVariable>another.flow.variable</FlowVariable> </Configurations> </ExternalCallout>
Riferimento elemento secondario
Le seguenti sezioni descrivono gli elementi secondari di ExternalCallout
.
<TimeoutMs>
Il timeout in millisecondi per le richieste gRPC. <TimeoutMs>
deve essere
un numero positivo.
<GrpcConnection>
L'elemento <GrpcConnection>
imposta il server gRPC come un
TargetServer
esistente, specificato dall'attributo name
. Consulta la pagina di riferimento delle risorse
TargetServer
.
Nota: il
protocollo per TargetServer
deve essere GRPC
.
Ad esempio, il seguente codice
<GrpcConnection> <Server name="external-target-server"/> </GrpcConnection>
specifica che il server gRPC è un TargetServer
esistente denominato
external-target-server
.
Utilizza l'elemento <Authentication>
(descritto più avanti in questa sezione) per generare un token OpenID Connect emesso da Google per effettuare chiamate autenticate ai servizi basati su gRPC, ad esempio i servizi personalizzati ospitati in Cloud Run.
La tabella seguente descrive gli elementi secondari di
<GrpcConnection>
.
Elemento secondario | Obbligatorio? | Descrizione |
---|---|---|
<Server> elemento |
Obbligatorio | Specifica il server gRPC. |
<Authentication> elemento |
Optional | Genera un token OpenID Connect emesso da Google per effettuare chiamate autenticate a servizi basati su gRPC, come Cloud Run. |
<Server>
elemento
Specifica il server gRPC.
La seguente tabella descrive gli attributi dell'elemento <Server>
.
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
name |
Il nome di un |
N/D | Obbligatorio | Stringa |
<Authentication>
elemento
Genera un token OpenID Connect emesso da Google per effettuare chiamate autenticate a servizi basati su gRPC, come i servizi personalizzati ospitati in Cloud Run. L'utilizzo di questo elemento richiede i passaggi di configurazione e deployment descritti in Utilizzare l'autenticazione Google. Con la corretta configurazione, il criterio crea un token di autenticazione per te e lo aggiunge alla richiesta di servizio.
Questo elemento ha un elemento secondario obbligatorio: GoogleIDToken
.
Predefinito | N/D |
Obbligatorio? | Facoltativo. |
Tipo | Tipo complesso |
Elemento principale | <GrpcConnection> |
Elementi secondari |
<GoogleIDToken> |
L'elemento Authentication
utilizza la seguente sintassi:
Sintassi
<ExternalCallout> ... <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleIDToken> <Audience ref="variable-1">STRING</Audience> <IncludeEmail ref="variable-2">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </GrpcConnection> </ExternalCallout>
Esempio
L'esempio seguente mostra l'elemento GoogleIDToken
:
<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1"> <DisplayName>External-Callout-1</DisplayName> <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication> </GrpcConnection> <TimeoutMs>5000</TimeoutMs> <Configurations> <Property name="with.request.content">true</Property> <Property name="with.request.headers">true</Property> <Property name="with.response.content">true</Property> <Property name="with.response.headers">true</Property> <FlowVariable>example.flow.variable</FlowVariable> <FlowVariable>another.flow.variable</FlowVariable> </Configurations> </ExternalCallout>
Attributi
Nessuno.
Elemento secondario <HeaderName>
Per impostazione predefinita, quando è presente una configurazione di autenticazione, Apigee genera un token di connessione e lo inserisce nell'intestazione Authorization
del messaggio inviato al sistema di destinazione.
L'elemento HeaderName
consente di specificare il nome di un'intestazione diversa
per contenere il token di connessione. Questa funzionalità è particolarmente utile quando la destinazione è un servizio Cloud Run che utilizza l'intestazione X-Serverless-Authorization
. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata nella richiesta.
Predefinito | N/D |
Obbligatorio? | No |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | Nessuna selezione |
L'elemento HeaderName
utilizza la seguente sintassi:
Sintassi
<ExternalCallout> ... <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleIDToken> ... </GoogleIDToken> </Authentication> ... </ExternalCallout>
Con stringa statica
In questo esempio, il token di connessione generato viene aggiunto, per impostazione predefinita, a un'intestazione denominata X-Serverless-Authorization
che viene inviata al sistema di destinazione. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata nella richiesta.
<Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication>
Con riferimento alla variabile
In questo esempio, il token di connessione generato viene aggiunto, per impostazione predefinita, a un'intestazione denominata X-Serverless-Authorization
che viene inviata al sistema di destinazione. Se my-variable
ha un valore, questo viene utilizzato
al posto della stringa predefinita. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata nella richiesta.
<Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication>
Elemento secondario <GoogleIDToken>
Genera token OpenID Connect emessi da Google per effettuare chiamate autenticate ai servizi Google, ad esempio i servizi personalizzati ospitati in Cloud Run.
Predefinito | N/D |
Obbligatorio? | Obbligatorio |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | <Audience> <IncludeEmail> |
L'elemento GoogleIDToken
utilizza la seguente sintassi:
Sintassi
<ExternalCallout> ... <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <GoogleIDToken> <Audience ref="context-variable" useTargetUrl='BOOLEAN'>STRING</Audience> <IncludeEmail ref="context-variable">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </GrpcConnection> </ExternalCallout>
Esempio
L'esempio seguente mostra l'elemento GoogleIDToken
:
<Authentication> <GoogleIDToken> <Audience>https://httpserver0-bar.run.app</Audience> <IncludeEmail>true</IncludeEmail> </GoogleIDToken> </Authentication>
Elemento secondario <Audience>
Il pubblico del token di autenticazione generato, ad esempio l'API o l'account a cui il token concede l'accesso.
Se il valore di Audience
è vuoto, ref
è vuoto o si risolve in un
valore vuoto e useTargetUrl
è true
, allora "https://" +
(host del server di destinazione gRPC) viene utilizzato come pubblico.
Ad esempio, se l'host del server è my-grpc-server-java.a.run.app
, il
pubblico utilizzato sarà https://my-grpc-server-java.a.run.app
.
Per impostazione predefinita, useTargetUrl
è false
.
<Audience>explicit-audience-value-here</Audience> or: <Audience ref='variable-name-here'/> or: <Audience ref='variable-name-here' useTargetUrl='true'/> or: <Audience useTargetUrl='true'/>
Predefinito | N/D |
Obbligatorio? | Obbligatorio |
Tipo | Stringa |
Elemento principale | <GoogleIDToken> |
Elementi secondari | Nessuno. |
Elemento secondario <IncludeEmail>
Se impostato su true
, il token di autenticazione generato conterrà le attestazioni dell'account di servizio email
e email_verified
.
Predefinito | false |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale | <GoogleIDToken> |
Elementi secondari | Nessuno. |
<Configurations>
L'elemento <Configurations>
ti consente di configurare vari aspetti delle norme per i callout esterni, tra cui <Property>
e <FlowVariable>
.
La tabella seguente descrive gli elementi secondari di
<Configurations>
.
Elemento secondario | Obbligatorio? | Descrizione |
---|---|---|
<Property> |
Obbligatorio | Specifica se le intestazioni e/o i contenuti della richiesta/risposta verranno inviati al
server. I valori possibili sono |
<FlowVariable> |
Obbligatorio | Specifica quali variabili di flusso aggiuntive devono essere inviate al server. |
<Property>
L'elemento <Property>
specifica se le intestazioni e/o i contenuti
della richiesta/risposta verranno inviati al server. I valori possibili sono true
(l'articolo verrà inviato) o false
(l'articolo non verrà inviato). Il valore predefinito è false
.
La seguente tabella descrive gli attributi dell'elemento <Property>
.
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
name |
Specifica i contenuti che verranno inviati al server. I valori possibili per
|
N/D | Obbligatorio | Stringa |
<FlowVariable>
L'elemento <FlowVariable>
specifica quali variabili di flusso aggiuntive
verranno inviate al server. Il valore di
<FlowVariable>
è un prefisso di una variabile, anziché il nome completo della variabile.
Ad esempio , se l'elemento a.b.c
, il valore di una variabile denominata a.b.c
verrà inviato al server. Allo stesso modo, il valore di una variabile denominata a.b.c.my-variable
verrà inviato al server. Tuttavia, il valore di una variabile
denominata a.x.another-variable
non verrà inviato perché non ha il
prefisso a.b.c
. Ecco alcuni esempi.
<Configurations> <FlowVariable>a.b.c</FlowVariable> <FlowVariable>d.e.f</FlowVariable> </Configurations>
Riferimento errore
Errori di deployment
Nome errore | Causa |
---|---|
FAILED_PRECONDITION |
Questo errore si verifica se l'account di servizio non è presente quando il proxy è configurato con il tag <Authentication> .
Ad esempio: Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service account identity, but one was not provided with the request. |
PERMISSION_DENIED |
Questo errore si verifica se si verifica un problema di autorizzazione con l'account di servizio se il proxy è configurato con il tag <Authentication>. Possibili cause:
|
Errori di runtime
La tabella seguente descrive gli errori di runtime, che possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa |
---|---|---|
GrpcTlsInitFailed |
500 |
Questo errore si verifica in caso di problemi con l'inizializzazione di TLS con il server gRPC (ad esempio problemi con l'archivio chiavi o l'archivio attendibilità). |
steps.externalcallout.[error_code] |
500 |
|
steps.externalcallout.ExecutionError |
500 |
Questo errore si verificherà se si verificano altre eccezioni durante l'esecuzione di questo criterio. L'eccezione sottostante verrà esposta nella stringa di errore. Se si è verificato un problema con le credenziali del server gRPC, l'errore sarà simile al seguente: { "fault": { "faultstring": "Encountered the following exception while sending the gRPC request or processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed to obtain metadata].", "detail": { "errorcode": "steps.externalcallout.ExecutionError" } } } Puoi esaminare i log dell'MP per ulteriori puntatori per il debug. |
googletoken.EmptyIDTokenAudience |
500 |
|
steps.externalcallout.ExecutionError
con la stringa di errore:
|
500 |
Questo errore si verifica se il proxy API è configurato con l'elemento
|
steps.externalcallout.ExecutionError con stringa di errore contenente
PERMISSION DENIED .
Ad esempio, la stringa di errore sarà simile alla seguente per Cloud Run:
|
500 |
Questo errore si verifica se il proxy API è configurato con l'elemento
|
Errori vari
La tabella seguente descrive vari errori. Scopri la causa per ulteriori dettagli.
Codice di errore | Causa |
---|---|
ReferencesExistToGrpcServer |
Questo errore si verifica se un utente tenta di eliminare un server di destinazione gRPC, ma il server è ancora utilizzato da altri criteri. |
Guasti
Le variabili di errore nella seguente tabella sono impostate per tutti i criteri per impostazione predefinita. Consulta la pagina Variabili specifiche per gli errori dei criteri.
Variabili | Dove | Esempi |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, indicato nella tabella Errori di runtime riportata sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. |
fault.name corrisponde a "ExecutionError". |
externalcallout.[policy_name].failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. |
externalcallout.ExternalCallout-1.failed = true |