Norme relative a PublishMessage

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Il criterio PublishMessage consente di pubblicare le informazioni sul flusso del proxy API in un argomento Google Cloud Pub/Sub. Pub/Sub di Google consente ai servizi di comunicare in modo asincrono, con una latenza notevolmente inferiore. Per saperne di più su Pub/Sub, consulta Che cos'è Pub/Sub? Le informazioni che vuoi pubblicare in un argomento Pub/Sub possono essere un testo letterale o una variabile di flusso. Puoi anche specificare una combinazione di testo letterale e variabili di flusso utilizzando un modello di messaggio.

Se la richiesta di pubblicazione ha esito positivo, Apigee imposta la variabile di flusso publishmessage.message.id sul valore restituito dal server Pub/Sub. Per ulteriori informazioni, consulta la sezione Variabili di flusso.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.

Nota:

• Puoi pubblicare un messaggio in un solo argomento utilizzando il criterio PublishMessage. Se vuoi pubblicare un messaggio in più argomenti, utilizza più criteri PublishMessage (un criterio per ogni argomento).
• Per eseguire il criterio PublishMessage, devi abilitare le API Pub/Sub per il tuo progetto Google Cloud. Per ulteriori informazioni sull'abilitazione delle API per un progetto Google Cloud, vedi Abilitazione e disabilitazione dei servizi.

Autenticazione e deployment del proxy

Per eseguire il criterio PublishMessage, è necessario un token di autenticazione. Tuttavia, non è presente alcun elemento <Authentication> esplicito nella definizione del criterio. Per utilizzare l'autenticazione Google, devi eseguire il deployment del proxy API, che aggiunge il token di autenticazione alla richiesta in background. Per informazioni su come eseguire il deployment di un proxy API che utilizza l'autenticazione Google, consulta Passaggi di deployment. Oltre a utilizzare l'autenticazione Google nel proxy API, devi eseguire il deployment del proxy API con un account di servizio che abbia un ruolo con l'autorizzazione pubsub.topics.publish. Per saperne di più sui ruoli di Identity and Access Management (IAM) per Pub/Sub, consulta Autorizzazioni e ruoli.

<PublishMessage>

Specifica il criterio PublishMessage.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Tipo complesso
Elemento principale	N/D
Elementi secondari	<Attributes> <CloudPubSub> <DisplayName> <IgnoreUnresolvedVariables> <Source> <UseMessageAsSource>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <PublishMessage>:

Elemento secondario	Obbligatorio?	Descrizione
<Attributes>	Facoltativo	Un insieme di attributi da allegare al messaggio Pub/Sub.
<CloudPubSub>	Obbligatorio	Elemento principale di <Topic>. L'elemento <Topic> specifica l'argomento Pub/Sub in cui vuoi pubblicare il messaggio.
<DisplayName>	Facoltativo	Un nome personalizzato per il criterio.
<IgnoreUnresolvedVariables>	Facoltativo	Specifica se l'elaborazione si interrompe se Apigee rileva una variabile non risolta.
<Source>	Facoltativo	Specifica il messaggio da pubblicare nell'argomento Pub/Sub. Questo elemento è facoltativo, ma devi utilizzare <Source> o <UseMessageAsSource>.
<UseMessageAsSource>	Facoltativo	Specifica il messaggio da pubblicare nell'argomento Pub/Sub. Questo elemento è facoltativo, ma devi utilizzare <Source> o <UseMessageAsSource>.
Altri elementi secondari
<Topic>	Obbligatorio	Un elemento secondario di <CloudPubSub>. Specifica l'argomento Pub/Sub a cui vuoi pubblicare il messaggio.

L'elemento <PublishMessage> utilizza la seguente sintassi:

Sintassi

<PublishMessage continueOnError="[true|false]" enabled="[true|false]" name="Publish-Message-1">
    <DisplayName>DISPLAY_NAME</DisplayName>
    <Source>SOURCE_VALUE</Source>
    <CloudPubSub>
        <Topic>TOPIC_NAME</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PublishMessage>

Esempio - Origine

L'esempio seguente mostra la definizione del criterio <PublishMessage>:

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>this is a message template {flow-variable1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

Esempio - UseMessageAsSource

Questo criterio <PublishMessage> specifica l'elemento UseMessageAsSource:

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-2">
    <UseMessageAsSource>request</UseMessageAsSource>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

Esempio - Attributi

Questo criterio <PublishMessage> specifica l'elemento Attributes:

<PublishMessage name="Publish-Message-3">
  <Source>this is a message template {flow-variable1}</Source>
  <Attributes>
    <Attribute name='attr-name-0'>fixed-value</Attribute>
    <Attribute name='another-attribute-name'>{request.queryparam.attr1}</Attribute>
    <Attribute name='a-third-attribute-name'>{request.queryparam.attr2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
  </CloudPubSub>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
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	Ritirato	Questo attributo è stato ritirato.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <PublishMessage>.

<Attributes>

Specifica gli attributi da allegare al messaggio Pub/Sub.

Ogni attributo è una coppia chiave-valore. Il nome associato all'attributo deve essere univoco. Il valore di ciascuna viene determinato in modo dinamico in fase di runtime tramite un modello di messaggio.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Stringa
Elemento principale	<PublishMessage>
Elementi secondari	Nessuno

L'elemento <Attributes> utilizza la seguente sintassi:

Sintassi

  <Attributes>
    <Attribute name='NAME-1'>fixed-value</Attribute>
    <Attribute name='NAME-2'>{flow-variable}</Attribute>
    ...
    <Attribute name='NAME-N'>message template here {flow-variable:default-value}</Attribute>
  </Attributes>

Esempio 1

L'esempio seguente imposta un singolo attributo con un valore fisso nel messaggio durante la pubblicazione:

<PublishMessage name="PM-with-one-attribute">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{request.queryparam.message}</Source>
  <Attributes>
    <Attribute name='my-attribute-1'>fixed-value</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{request.queryparam.project}/topics/{request.queryparam.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

Esempio 2

L'esempio seguente imposta più attributi sul messaggio durante la pubblicazione; i valori di alcuni di questi vengono determinati dinamicamente in fase di runtime:

<PublishMessage name="PM-with-multiple-attributes">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{my-assembled-message}</Source>
  <Attributes>
    <Attribute name='attr-0'>fixed-value</Attribute>
    <Attribute name='attr-1'>{flow-variable1}</Attribute>
    <Attribute name='attr-2'>fixed portion {flow-variable2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito	N/D
Obbligatorio?	Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<Source>

Specifica il messaggio da pubblicare.

Il messaggio può essere un testo letterale, una variabile di flusso o una combinazione di entrambi sotto forma di modello di messaggio.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<PublishMessage>
Elementi secondari	Nessuno

L'elemento <Source> utilizza la seguente sintassi:

Sintassi

 <Source>SOURCE</Source>

Example-1

L'esempio seguente imposta il messaggio di origine sul valore della variabile di flusso flow-var-1:

<Source>{flow-var-1}</Source>

Example-2

Il seguente esempio utilizza un modello di messaggio per pubblicare un messaggio JSON con contenuti dinamici:

<PublishMessage name="PM-with-source-template">
  <Source>{
    "name": "value-1",
    "count": "{flow-variable1}",
    "action": "{flow-variable2}"
  }</Source>
  <Attributes>
    <Attribute name='content-type'>application/json</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

<CloudPubSub>

Elemento principale di <Topic>.

Puoi pubblicare in un solo argomento Pub/Sub. Pertanto, puoi avere un solo elemento <Topic> nell'elemento <CloudPubSub>.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Tipo complesso
Elemento principale	<PublishMessage>
Elementi secondari	<Topic>

L'elemento <CloudPubSub> utilizza la seguente sintassi:

Sintassi

<CloudPubSub>
  <Topic>TOPIC_NAME</Topic>
</CloudPubSub>

Esempio

L'esempio seguente mostra la dichiarazione dell'elemento <CloudPubSub>:

<CloudPubSub>
  <Topic>projects/{my-project}/topics/{my-topic}</Topic>
</CloudPubSub>

<Topic>

Specifica l'argomento Pub/Sub a cui vuoi pubblicare il messaggio <Source>.

Devi specificare il nome dell'argomento nel formato projects/project-id/topics/topic-name.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Stringa
Elemento principale	<CloudPubSub>
Elementi secondari	Nessuno

L'elemento <Topic> utilizza la seguente sintassi:

Sintassi

<Topic>TOPIC_NAME</Topic>

Esempio

L'esempio seguente specifica l'argomento Pub/Sub in cui pubblicare:

<Topic>projects/project-id-marketing/topics/topic-name-test1</Topic>

In questo esempio, project-id-marketing è l'ID progetto Google Cloud e topic-name-test1 è l'argomento in cui deve essere pubblicato il messaggio.

<UseMessageAsSource>

Specifica il messaggio da pubblicare.

Utilizza questo elemento come alternativa all'elemento <Source>. Il valore deve essere il nome di una variabile di flusso che fa riferimento a un messaggio, ad esempio request, response o message. Quando specifichi questo elemento, il criterio utilizza i contenuti del messaggio come messaggio da pubblicare. Devi utilizzare questo elemento anziché <Source> quando i contenuti del messaggio sono un flusso di ottetti che non può essere rappresentato come stringa, ad esempio i contenuti di un file binario.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<PublishMessage>
Elementi secondari	Nessuno

L'elemento <UseMessageAsSource> utilizza la seguente sintassi:

Sintassi

<PublishMessage name="PM-with-use-message-as-source">
  <UseMessageAsSource>MESSAGE_NAME</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flowvar1}/topics/{flowvar-topic}</Topic>
  </CloudPubSub>
</PublishMessage>

Example-1

L'esempio seguente indica al criterio di utilizzare il contenuto del messaggio di richiesta come payload per il messaggio Pub/Sub:

<PublishMessage name="PM-with-use-message-as-source">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <UseMessageAsSource>request</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

<IgnoreUnresolvedVariables>

Specifica se l'elaborazione si interrompe se Apigee rileva una variabile non risolta.

Valore predefinito	Falso
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<PublishMessage>
Elementi secondari	Nessuno

Imposta il valore su true per ignorare le variabili non risolte e continuare l'elaborazione; altrimenti false. Il valore predefinito è false.

Impostare <IgnoreUnresolvedVariables> su true è diverso dall'impostazione di continueOnError di <PublishMessage> su true. Se imposti continueOnError su true, Apigee ignora tutti gli errori, non solo quelli nelle variabili.

L'elemento <IgnoreUnresolvedVariables> utilizza la seguente sintassi:

Sintassi

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

Esempio

L'esempio seguente imposta <IgnoreUnresolvedVariables> su true:

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Variabili di flusso

Le variabili di flusso sono oggetti che contengono dati specifici e sono disponibili nel contesto di un flusso di proxy API. Queste variabili memorizzano informazioni come i dati del payload, il percorso URL, gli indirizzi IP e i dati dell'esecuzione dei criteri. Per ulteriori informazioni sulle variabili di flusso, consulta la sezione Utilizzare le variabili di flusso.

Se la policy PublishMessage viene pubblicata correttamente nell'argomento Pub/Sub, Apigee imposta la variabile di flusso publishmessage.message.id sul messageId restituito dal server Pub/Sub. La variabile di flusso è di tipo stringa ed è disponibile dal flusso di richiesta proxy in poi. In base al tuo requisito, puoi utilizzare la variabile di flusso in altre policy downstream. Tuttavia, se la pubblicazione non va a buon fine, Apigee non imposta la variabile publishmessage.message.id, e l'accesso a questa variabile causerà errori.

Per ulteriori informazioni sui vari tipi di variabili di flusso, consulta Riferimento alle variabili di flusso.

Codici di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto	Stato HTTP	Causa
steps.publishmessage.PermissionDeniedError	500	Questo errore si verifica quando l'account di servizio di runtime non può rubare l'identità dell'account di servizio proxy o quando l'account di servizio proxy non dispone dell'autorizzazione per pubblicare nell'argomento.
steps.publishmessage.ExecutionError	500	Questo errore si verifica se si è verificato un errore imprevisto durante la pubblicazione del messaggio in Pub/Sub. Puoi visualizzare i dettagli dell'errore nel messaggio di errore.
steps.publishmessage.MessageVariableNotMessageType	500	Questo errore si verifica se il nome della variabile specificato in UseMessageAsSource non può essere risolto o non è un tipo di messaggio.

Variabili di errore

Ogni volta che si verificano errori di esecuzione in un criterio, Apigee genera messaggi di errore. Puoi visualizzare questi messaggi di errore nella risposta di errore. Spesso i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del tuo prodotto. Ti consigliamo di personalizzare i messaggi di errore in base al tipo di errore per renderli più significativi.

Per personalizzare i messaggi di errore, puoi utilizzare le regole di errore o il criterio RaiseFault. Per informazioni sulle differenze tra le regole di errore e il criterio RaiseFault, consulta Regole di errore e criterio RaiseFault. Devi verificare la presenza di condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio RaiseFault. Apigee fornisce variabili di errore univoche per ogni criterio e i valori delle variabili di errore vengono impostati quando un criterio attiva errori di runtime. Utilizzando queste variabili, puoi verificare la presenza di condizioni di errore specifiche e intraprendere le azioni appropriate. Per ulteriori informazioni su come controllare le condizioni di errore, consulta Condizioni dell'edificio.

Variabili	Dove	Esempio
fault.name	fault.name può corrispondere a uno dei problemi elencati nella tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice dell'errore.	fault.name Matches "UnresolvedVariable"
publishmessage.POLICY_NAME.failed	POLICY_NAME è il nome specificato dall'utente del criterio che ha generato l'errore.	publishmessage.publish-message-1.failed = true

Per ulteriori informazioni sugli errori relativi alle norme, consulta Informazioni importanti sugli errori relativi alle norme