Norme relative a PublishMessage

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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 policy e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di policy.

Autenticazione e deployment del proxy

Per eseguire il criterio PublishMessage, è necessario un token di autenticazione. Tuttavia, non è presente un 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 della policy <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

L'esempio seguente 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, la policy 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 dell'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 saperne di più sui vari tipi di variabili di flusso, consulta Riferimento alle variabili di flusso.

Codici di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.publishmessage.PermissionDeniedError`	`500`	This error occurs when the runtime service account cannot impersonate the proxy service account or the proxy service account does not have the permission to publish to the topic.
`steps.publishmessage.ExecutionError`	`500`	This error occurs if there was an unexpected error while publishing the message to Pub/Sub. You can view the details of the error in the error message.
`steps.publishmessage.MessageVariableNotMessageType`	`500`	This error occurs if the variable name you specified in `UseMessageAsSource` cannot be resolved, or is not a message type.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

Variables	Where	Example
`fault.name`	The `fault.name` can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`publishmessage.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`publishmessage.publish-message-1.failed = true`

For more information about policy errors, see What you need to know about policy errors

Norme relative a PublishMessage Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Autenticazione e deployment del proxy

<PublishMessage>

Sintassi

Esempio - Origine

Esempio - UseMessageAsSource

Esempio - Attributi

Riferimento all'elemento secondario

<Attributes>

Sintassi

Esempio 1

Esempio 2

<DisplayName>

Sintassi

Esempio

<Source>

Sintassi

Example-1

Example-2

<CloudPubSub>

Sintassi

Esempio

<Topic>

Sintassi

Esempio

<UseMessageAsSource>

Sintassi

Example-1

<IgnoreUnresolvedVariables>

Sintassi

Esempio

Variabili di flusso

Codici di errore

Runtime errors

Fault variables

Norme relative a PublishMessage

`<PublishMessage>`

`<Attributes>`

`<DisplayName>`

`<Source>`

`<CloudPubSub>`

`<Topic>`

`<UseMessageAsSource>`

`<IgnoreUnresolvedVariables>`