Règle PublishMessage

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

La règle PublishMessage vous permet de publier vos informations de flux de proxy d'API dans un sujet Google Cloud Pub/Sub. Pub/Sub de Google permet aux services de communiquer de manière asynchrone, avec une latence nettement inférieure. Pour plus d'informations sur Pub/Sub, consultez la page Qu'est-ce que Pub/Sub ? Les informations que vous souhaitez publier sur un sujet Pub/Sub peuvent être un texte littéral ou une variable de flux. Vous pouvez également spécifier une combinaison de variables littérales de texte et de flux à l'aide d'un modèle de message.

Si la requête de publication aboutit, Apigee définit la variable de flux publishmessage.message.id sur la valeur renvoyée par le serveur Pub/Sub. Pour en savoir plus, consultez la section Variables de flux.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

Authentification et déploiement du proxy

Pour exécuter la règle PublishMessage, vous avez besoin d'un jeton d'authentification. Cependant, il n'y a pas d'élément <Authentication> explicite dans la définition de la règle. Vous devez déployer votre proxy d'API pour utiliser l'authentification Google, qui ajoute le jeton d'authentification à la requête en arrière-plan. Pour en savoir plus sur le déploiement d'un proxy d'API qui utilise l'authentification Google, consultez la page Procédure de déploiement. Outre l'utilisation de l'authentification Google dans votre proxy d'API, vous devez déployer votre proxy d'API avec un compte de service disposant d'un rôle avec l'autorisation pubsub.topics.publish. Pour en savoir plus sur les rôles IAM (Identity and Access Management) pour Pub/Sub, consultez la page Autorisations et rôles.

`<PublishMessage>`

Spécifie la règle PublishMessage.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Type complexe
Élément parent	ND
Éléments enfants	`<Attributes>` `<CloudPubSub>` `<DisplayName>` `<IgnoreUnresolvedVariables>` `<Source>` `<UseMessageAsSource>`

Le tableau suivant fournit une description détaillée des éléments enfants de <PublishMessage> :

Élément enfant	Obligatoire ?	Description
`<Attributes>`	Facultatif	Ensemble d'attributs à associer au message Pub/Sub.
`<CloudPubSub>`	Obligatoire	Élément parent de `<Topic>`. L'élément `<Topic>` spécifie le sujet Pub/Sub dans lequel vous souhaitez publier votre message.
`<DisplayName>`	Facultatif	Nom personnalisé de la règle.
`<IgnoreUnresolvedVariables>`	Facultatif	Spécifie si le traitement s'arrête si Apigee rencontre une variable non résolue.
`<Source>`	Facultatif	Spécifie le message à publier dans le sujet Pub/Sub. Cet élément est facultatif, mais vous devez utiliser `<Source>` ou `<UseMessageAsSource>`.
`<UseMessageAsSource>`	Facultatif	Spécifie le message à publier dans le sujet Pub/Sub. Cet élément est facultatif, mais vous devez utiliser `<Source>` ou `<UseMessageAsSource>`.
Autres éléments enfants
`<Topic>`	Obligatoire	Élément enfant de `<CloudPubSub>`. Spécifie le sujet Pub/Sub sur lequel vous souhaitez publier le message.

L'élément <PublishMessage> utilise la syntaxe suivante :

Syntaxe

<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>

Exemple : Source

L'exemple suivant montre la définition de la règle <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>

Exemple : UseMessageAsSource

Cette règle <PublishMessage> spécifie l'élément 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>

Exemple : Attributs

Cette règle <PublishMessage> spécifie l'élément 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>

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
`name`	ND	Obligatoire	Nom interne de la règle. La valeur de l'attribut `name` peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément `<DisplayName>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
`continueOnError`	faux	Facultatif	Définissez sur `false` pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur `true` pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
`enabled`	true	Facultatif	Définissez sur `true` pour appliquer la règle. Définissez sur `false` pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
`async`	faux	Obsolète	Cet attribut est obsolète.

Référence d'élément enfant

Cette section décrit les éléments enfants de <PublishMessage>.

`<Attributes>`

Spécifie les attributs à associer au message Pub/Sub.

Chaque attribut est une paire clé/valeur. Le nom associé à l'attribut doit être unique. La valeur de chacun est déterminée de manière dynamique au moment de l'exécution via un modèle de message.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Chaîne
Élément parent	`<PublishMessage>`
Éléments enfants	Aucun

L'élément <Attributes> utilise la syntaxe suivante :

Syntaxe

  <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>

Exemple 1

L'exemple suivant définit un seul attribut avec une valeur fixe sur le message tel qu'il est publié :

<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>

Exemple 2

L'exemple suivant définit plusieurs attributs sur le message lors de sa publication. Les valeurs de certains d'entre eux sont déterminées de manière dynamique au moment de l'exécution :

<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>`

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	N/A
Obligatoire ?	Facultatif. Si vous omettez `<DisplayName>`, la valeur de l'attribut `name` de la règle est utilisée.
Type	Chaîne
Élément parent	<`PolicyElement`>
Éléments enfants	Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

`<Source>`

Spécifie le message à publier.

Le message peut être un texte littéral, une variable de flux ou une combinaison des deux sous la forme d'un modèle de message.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	`<PublishMessage>`
Éléments enfants	Aucun

L'élément <Source> utilise la syntaxe suivante :

Syntaxe

 <Source>SOURCE</Source>

Exemple 1

L'exemple suivant définit le message source sur la valeur de la variable de flux flow-var-1 :

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

Exemple 2

L'exemple suivant utilise un modèle de message pour publier un message JSON avec du contenu dynamique :

<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>`

Élément parent de <Topic>.

Vous ne pouvez publier que sur un seul sujet Pub/Sub. Par conséquent, vous ne pouvez avoir qu'un seul élément <Topic> dans l'élément <CloudPubSub>.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Type complexe
Élément parent	`<PublishMessage>`
Éléments enfants	`<Topic>`

L'élément <CloudPubSub> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant montre la déclaration de l'élément <CloudPubSub> :

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

`<Topic>`

Spécifie le sujet Pub/Sub sur lequel vous souhaitez publier le message <Source>.

Vous devez spécifier le nom du sujet au format projects/project-id/topics/topic-name.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Chaîne
Élément parent	`<CloudPubSub>`
Éléments enfants	Aucun

L'élément <Topic> utilise la syntaxe suivante :

Syntaxe

<Topic>TOPIC_NAME</Topic>

Exemple

L'exemple suivant spécifie le sujet Pub/Sub sur lequel publier :

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

Dans cet exemple, project-id-marketing correspond à votre ID de projet Google Cloud et topic-name-test1 au sujet sur lequel le message doit être publié.

`<UseMessageAsSource>`

Spécifie le message à publier.

Utilisez-le comme alternative à l'élément <Source>. La valeur doit être le nom d'une variable de flux faisant référence à un message, tel que request, response ou message. Lorsque vous spécifiez cet élément, la règle utilise le contenu du message comme message à publier. Vous devez utiliser cet élément plutôt que <Source> lorsque le contenu du message est un flux d'octets qui ne peut pas être représenté sous forme de chaîne (par exemple, le contenu d'un fichier binaire).

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	`<PublishMessage>`
Éléments enfants	Aucun

L'élément <UseMessageAsSource> utilise la syntaxe suivante :

Syntaxe

<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>

Exemple 1

L'exemple suivant indique à la règle d'utiliser le contenu du message de la requête comme charge utile du message 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>`

Spécifie si le traitement s'arrête si Apigee rencontre une variable non résolue.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	`<PublishMessage>`
Éléments enfants	Aucun

Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, ou false. La valeur par défaut est false.

Définir <IgnoreUnresolvedVariables> sur true n'est pas la même chose que définir la valeur continueOnError de <PublishMessage> sur true. Si vous définissez continueOnError sur true, Apigee ignore toutes les erreurs, et pas seulement les erreurs dans les variables.

L'élément <IgnoreUnresolvedVariables> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant définit <IgnoreUnresolvedVariables> sur true :

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Variables de flux

Les variables de flux sont des objets contenant des données spécifiques et sont disponibles dans le contexte d'un flux de proxy d'API. Ces variables stockent des informations telles que les informations de charge utile, le chemin d'URL, les adresses IP et les données issues de l'exécution de la règle. Pour en savoir plus sur les variables de flux, consultez la section Utiliser des variables de flux.

Si la règle PublishMessage publie correctement sur le sujet Pub/Sub, Apigee définit la variable de flux publishmessage.message.id sur l'identifiant messageId renvoyé par le serveur Pub/Sub. La variable de flux est de type chaîne. Elle est disponible à partir du flux de requête du proxy. Selon vos besoins, vous pouvez utiliser la variable de flux dans d'autres règles en aval. Toutefois, si la publication échoue, Apigee ne définit pas la variable publishmessage.message.id et l'accès à cette variable entraîne des erreurs.

Pour en savoir plus sur les différents types de variables de flux, consultez la documentation de référence sur les variables.

Codes d'erreur

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

Règle PublishMessage Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Authentification et déploiement du proxy

<PublishMessage>

Syntaxe

Exemple : Source

Exemple : UseMessageAsSource

Exemple : Attributs

Référence d'élément enfant

<Attributes>

Syntaxe

Exemple 1

Exemple 2

<DisplayName>

Syntaxe

Exemple

<Source>

Syntaxe

Exemple 1

Exemple 2

<CloudPubSub>

Syntaxe

Exemple

<Topic>

Syntaxe

Exemple

<UseMessageAsSource>

Syntaxe

Exemple 1

<IgnoreUnresolvedVariables>

Syntaxe

Exemple

Variables de flux

Codes d'erreur

Runtime errors

Fault variables

Règle PublishMessage

`<PublishMessage>`

`<Attributes>`

`<DisplayName>`

`<Source>`

`<CloudPubSub>`

`<Topic>`

`<UseMessageAsSource>`

`<IgnoreUnresolvedVariables>`