Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
Cosa
Il criterio sui callout esterni ti 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 e modificare facilmente le variabili di flusso all'interno del flusso di un proxy.
Apigee comunica con un server gRPC tramite un criterio di callout esterno mediante un'API. Apigee utilizza l'API per inviare variabili di flusso al server gRPC. All'interno del server gRPC, puoi leggere e modificare, a seconda della variabile, le variabili di flusso elencate Riferimento per le variabili di flusso del criterio, nonché altre variabili da te 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 nel seguente modo:
- Apigee invia un messaggio contenente le variabili di flusso al tuo server gRPC.
- Il codice del server gRPC viene eseguito, accedendo alle variabili e modificandole come definito in il codice. Il server gRPC quindi invia una risposta contenente tutte le variabili di flusso ad Apigee.
- Apigee legge la risposta dal server gRPC. Se vengono aggiunte variabili o le variabili di flusso modificabili vengono modificate, vengono aggiornate in Apigee.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.
Per saperne di più sull'invio di richieste gRPC, consulta i seguenti link:
<ExternalCallout>
Definisce un criterio per i callout esterni.
<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. |
Nella tabella seguente vengono descritti gli elementi secondari di
<ExternalCallout>
.
Elemento secondario | Obbligatorio | Descrizione |
---|---|---|
<TimeoutMs> |
Obbligatorio | Timeout della richiesta in millisecondi per le richieste gRPC. |
<GrpcConnection> |
Obbligatorio | Specifica il nome di un TargetServer esistente da utilizzare come server gRPC
a cui inviare richieste.
|
<Configurations> |
Facoltativo | Consente di configurare vari aspetti
delle norme sui callout esterni,
inclusi <Property> e <FlowVariable>
elementi. |
Esempio 1
Esempi pratici di callout esterni sono disponibili nella sezione External Callout Samples (Campioni di callout esterni) su GitHub.
L'esempio seguente illustra la configurazione di un criterio per i callout esterni.
<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>
: includi contenuti di richiesta e risposta, ma non le intestazioni di richiesta e risposta, richiesta inviata al server gRPC.<FlowVariable>
: includi dati aggiuntivi variabili di flussoexample1.flow.variable
eexample2.flow.variable
, specificato dagli elementiFlowVariable
, nella richiesta inviata a gRPC o server web.
Esempio 2
Nell'esempio seguente, l'attributo useTargetUrl
dell'elemento Audience
è impostato su true
. Quando il valore del campo useTargetUrl
è true
,
come pubblico viene utilizzato il nome host del server di destinazione gRPC. Per
Ad esempio, se l'host del server è my-grpc-server-java.a.run.app
, il segmento di pubblico
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>
Timeout della richiesta in millisecondi per le richieste gRPC. <TimeoutMs>
deve essere
un numero positivo.
<GrpcConnection>
L'elemento <GrpcConnection>
imposta il server gRPC come un server
TargetServer
, specificato dall'attributo name
. Consulta le
TargetServer
.
Nota: il
.
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
per effettuare chiamate autenticate a servizi basati su gRPC, ad esempio servizi personalizzati ospitati in
Cloud Run.
Nella tabella seguente vengono descritti 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 ai servizi basati su gRPC, ad esempio Cloud Run. |
<Server>
elemento
Specifica il server gRPC.
Nella tabella seguente vengono descritti 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, ad esempio servizi personalizzati ospitati in Cloud Run. L'utilizzo di questo elemento richiede i passaggi di configurazione e deployment descritti in Utilizzo dell'autenticazione Google. Con configurazione corretta, il criterio crea per te un token di autenticazione 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
Nell'esempio seguente viene mostrato 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.
<HeaderName> elemento secondario
Per impostazione predefinita, quando è presente una configurazione di autenticazione, Apigee genera un portatore.
e lo inserisce nell'intestazione Authorization
del messaggio inviato al sistema di destinazione.
L'elemento HeaderName
ti consente di specificare il nome di un'intestazione diversa
il token di connessione. Questa funzionalità è particolarmente utile quando la destinazione è Cloud Run
che utilizza l'intestazione X-Serverless-Authorization
. L'intestazione Authorization
,
se presente, non viene modificato e viene inviato nella richiesta.
Predefinito | N/D |
Obbligatorio? | No |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | Nessuno |
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 inviato al sistema di destinazione. L'intestazione Authorization
,
se presente, non viene modificato e viene inviato nella richiesta.
<Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication>
Con riferimento variabile
In questo esempio, il token di connessione generato viene aggiunto, per impostazione predefinita, a un'intestazione denominata X-Serverless-Authorization
che viene inviato al sistema di destinazione. Se my-variable
ha un valore, questo viene utilizzato
anziché la stringa predefinita. L'intestazione Authorization
,
se presente, non viene modificato e viene inviato nella richiesta.
<Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication>
<GoogleIDToken> elemento secondario
Genera token OpenID Connect emessi da Google per effettuare chiamate autenticate ai servizi Google, ad esempio 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
Nell'esempio seguente viene mostrato l'elemento GoogleIDToken
:
<Authentication> <GoogleIDToken> <Audience>https://httpserver0-bar.run.app</Audience> <IncludeEmail>true</IncludeEmail> </GoogleIDToken> </Authentication>
<Audience> elemento secondario
Il pubblico del token di autenticazione generato, ad esempio l'API o l'account che che concede l'accesso.
Se il valore Audience
è vuoto, il valore ref
è vuoto o viene risolto in un
valore vuoto e useTargetUrl
è true
, poi "https://" +
(nome host del server di destinazione gRPC) viene utilizzato come pubblico.
Ad esempio, se l'host del server è my-grpc-server-java.a.run.app
, la classe
il segmento di pubblico utilizzato sarà https://my-grpc-server-java.a.run.app
.
Per impostazione predefinita, il valore di 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. |
<IncludeEmail> elemento secondario
Se impostato su true
, il token di autenticazione generato conterrà il valore
account di servizio email
e email_verified
rivendicazioni.
Predefinito | falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale | <GoogleIDToken> |
Elementi secondari | Nessuno. |
<Configurations>
L'elemento <Configurations>
ti consente di configurare vari aspetti di
le norme sui callout esterni,
tra cui <Property>
e <FlowVariable>
.
Nella tabella seguente vengono descritti gli elementi secondari di
<Configurations>
.
Elemento secondario | Obbligatorio? | Descrizione |
---|---|---|
<Property> |
Obbligatorio | Specifica se le intestazioni e/o i contenuti della richiesta/risposta verranno inviati a
il server. I valori possibili sono |
<FlowVariable> |
Obbligatorio | Specifica quali variabili di flusso aggiuntive devono essere inviate al server. |
<Property>
L'elemento <Property>
specifica se richiesta/risposta
intestazioni e/o contenuti verranno inviati al server. I valori possibili sono true
(l'articolo verrà inviato) o false
(l'articolo non verrà inviato). Il valore predefinito
è false
.
Nella tabella seguente vengono descritti gli attributi dell'elemento <Property>
.
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
name |
Specifica a quali contenuti verranno inviati
il server. I valori possibili per
|
N/D | Obbligatorio | Stringa |
<FlowVariable>
L'elemento <FlowVariable>
specifica quali variabili di flusso aggiuntive
verrà inviato al server. Il valore di
<FlowVariable>
è il prefisso di una variabile anziché il nome completo della variabile.
Ad esempio , se l'elemento a.b.c
, il valore
verrà inviato al server il valore di una variabile denominata a.b.c
. Analogamente, il valore
di una variabile
con nome a.b.c.my-variable
verrà inviata al server. Ma il valore di una variabile
denominato a.x.another-variable
non verrà inviato perché non presenta
prefisso a.b.c
. Ecco alcuni esempi
<Configurations> <FlowVariable>a.b.c</FlowVariable> <FlowVariable>d.e.f</FlowVariable> </Configurations>
Riferimento errori
Errori di deployment
Nome errore | Causa |
---|---|
FAILED_PRECONDITION |
Questo errore si verifica se l'account di servizio non è presente quando il proxy viene
configurate 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
il proxy viene
configurate con il modulo <Authentication> del tag. Possibili cause:
|
Errori di runtime
La tabella seguente descrive gli errori di runtime, che possono verificarsi durante l'esecuzione del criterio.
Codice di errore | Stato HTTP | Causa |
---|---|---|
GrpcTlsInitFailed |
500 |
Questo errore si verifica in caso di problemi con l'inizializzazione di TLS con gRPC server (ad esempio per problemi relativi ad archivi chiavi o truststore). |
steps.externalcallout.[error_code] |
500 |
|
steps.externalcallout.ExecutionError |
500 |
Questo errore si verifica se durante l'esecuzione si verificano altre eccezioni . L'eccezione sottostante sarà esposta nella stringa di errore. Se si è verificato un problema con le credenziali del server gRPC, l'errore verrà visualizzato ad esempio: { "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 di MP per ulteriori puntatori di debug. |
googletoken.EmptyIDTokenAudience |
500 |
|
steps.externalcallout.ExecutionError
con stringa di errore:
|
500 |
Questo errore si verifica se il proxy API è configurato con l'elemento
|
steps.externalcallout.ExecutionError con faultstring contenente
PERMISSION DENIED .
Ad esempio, la stringa di errore sarà simile al seguente per Cloud Run:
|
500 |
Questo errore si verifica se il proxy API è configurato con l'
|
Errori vari
Nella tabella seguente sono descritti vari errori. Per ulteriori dettagli, individua la causa.
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 altre norme. |
Errori
Le variabili di errore nella tabella seguente sono impostate per tutti i criteri per impostazione predefinita. Consulta Variabili specifiche degli errori dei criteri.
Variabili | Dove | Esempi |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come elencato nella sezione Errori di runtime
riportata sopra. Il nome dell'errore è l'ultima parte del codice di 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 |