Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
Aperçu
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. Tous les utilisateurs n'ont pas besoin de connaître les types de règles et d'environnements. 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 | ND |
| Obligatoire ? | Obligatoire |
| Type | Type complexe |
| Élément parent | ND |
| Éléments enfants |
<CloudPubSub><DisplayName><Source> |
Le tableau suivant fournit une description détaillée des éléments enfants de <PublishMessage> :
| Élément enfant | Requis ? | Description |
|---|---|---|
<CloudPubSub> |
Requis | É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> |
Requis | Spécifie le message à publier. |
| Autres éléments enfants | ||
<Topic> |
Requis | Spécifie le sujet Pub/Sub sur lequel vous souhaitez publier le message. |
L'élément <PublishMessage> utilise la syntaxe suivante :
Syntaxe
<?xml version="1.0" encoding="UTF-8"?><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
L'exemple suivant montre la définition de la règle <PublishMessage> :
<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
<DisplayName>Publish Message-1</DisplayName>
<Source>{flow-variable-1}</Source>
<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 Vous pouvez également utiliser l'élément |
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 :
|
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>.
<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 | ND |
| 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 | Aucune |
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 | ND |
| Obligatoire ? | Obligatoire |
| Type | Chaîne |
| Élément parent |
<PublishMessage> |
| Éléments enfants | Aucune |
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 définit le message source sur source-message-text-01 :
<Source>source-message-text-01</Source>
<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 | ND |
| 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/{request.header.project}/topics/{request.header.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 | ND |
| Obligatoire ? | Obligatoire |
| Type | Type complexe |
| Élément parent |
<CloudPubSub> |
| Éléments enfants | Aucune |
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 <Source> doit être publié.
<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
Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.
Erreurs d'exécution
Ces erreurs peuvent se produire lors de l'exécution de la règle.
| Code d'erreur | État HTTP | Cause |
|---|---|---|
steps.publishmessage.PermissionDeniedError |
500 |
Cette erreur se produit lorsque le compte de service d'exécution ne peut pas emprunter l'identité du compte de service proxy ou que le compte de service proxy n'est pas autorisé à publier sur le sujet. |
steps.publishmessage.ExecutionError |
500 |
Cette erreur se produit si une erreur inattendue s'est produite lors de la publication du message dans Pub/Sub. Vous pouvez afficher les détails de l'erreur dans le message d'erreur. |
Variables de panne
Chaque fois qu'une règle comporte des erreurs d'exécution, Apigee génère des messages d'erreur. Vous pouvez afficher ces messages d'erreur dans la réponse d'erreur. Souvent, les messages d'erreur générés par le système peuvent ne pas être pertinents dans le contexte de votre produit. Vous pouvez personnaliser les messages d'erreur en fonction du type d'erreur pour rendre les messages plus significatifs.
Pour personnaliser les messages d'erreur, vous pouvez utiliser des règles d'erreur ou la règle RaiseFault. Pour en savoir plus sur les différences entre les règles d'erreur et la règle RaiseFault, consultez la section Règles d'erreur et règle RaiseFault.
Vous devez vérifier les conditions à l'aide de l'élément Condition dans les règles d'erreur et dans la règle RaiseFault.
Apigee fournit des variables d'erreur propres à chaque règle et les valeurs des variables d'erreur sont définies lorsqu'une règle déclenche des erreurs d'exécution.
En utilisant ces variables, vous pouvez vérifier des conditions d'erreur spécifiques et prendre les mesures appropriées. Pour en savoir plus sur la vérification des conditions d'erreur, consultez la page Conditions de création.
| Variables | Où : | Exemple |
|---|---|---|
fault.name |
L'élément fault.name peut correspondre à n'importe quelle erreur affichée dans le tableau Erreurs d'exécution.
Le nom d'erreur est la dernière partie du code d'erreur. |
fault.name Matches "UnresolvedVariable" |
publishmessage.POLICY_NAME.failed |
POLICY_NAME est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. | publishmessage.publish-message-1.failed = true |