Cette page explique comment créer des abonnements Pub/Sub avec des filtres.
Lorsque vous recevez des messages d'un abonnement avec un filtre, vous ne recevez que ceux qui correspondent au filtre. Le service Pub/Sub reconnaît automatiquement les messages qui ne correspondent pas au filtre. Vous pouvez filtrer les messages en fonction de leurs attributs, mais pas en fonction des données du message.
Vous pouvez associer plusieurs abonnements à un sujet, et chaque abonnement peut avoir un filtre différent.
Par exemple, si un sujet reçoit des actualités de différentes régions du monde, vous pouvez configurer un abonnement pour filtrer les actualités publiées uniquement dans une région spécifique. Pour cette configuration, vous devez vous assurer que l'un des attributs du message de sujet indique la région de publication des actualités.
Lorsque vous recevez des messages d'un abonnement avec un filtre, des frais de message sortant ne vous sont pas facturés pour les messages reconnus par Pub/Sub. Des frais de distribution de messages et de stockage associé à Seek vous sont facturés pour ces messages.
Créer un abonnement avec un filtre
Les abonnements pull et push peuvent comporter des filtres. Tous les abonnés peuvent recevoir des messages des abonnements avec des filtres, y compris ceux qui utilisent l'API StreamingPull.
Vous pouvez créer un abonnement avec un filtre à l'aide de la console Google Cloud, de Google Cloud CLI, des bibliothèques clientes ou de l'API Pub/Sub.
Console
Pour créer un abonnement pull avec filtre, procédez comme suit :
Dans la console Google Cloud, accédez à la page Abonnements.
Cliquez sur Créer un abonnement.
Saisissez l'ID de l'abonnement.
Choisissez ou créez un sujet dans le menu déroulant. L'abonnement reçoit les messages du sujet.
Dans la section Filtre d'abonnement, saisissez l'expression du filtre.
Cliquez sur Create (Créer).
Pour créer un abonnement push avec un filtre, procédez comme suit :
Dans la console Google Cloud, accédez à la page Abonnements.
Cliquez sur Créer un abonnement.
Saisissez l'ID de l'abonnement.
Choisissez ou créez un sujet dans le menu déroulant. L'abonnement reçoit les messages du sujet.
Dans la section Type de distribution, cliquez sur Push.
Dans le champ URL du point de terminaison, saisissez l'URL du point de terminaison push.
Dans la section Filtre d'abonnement, saisissez l'expression du filtre.
Cliquez sur Create (Créer).
gcloud
Pour créer un abonnement pull avec un filtre, exécutez la commande gcloud pubsub subscriptions create
avec l'option --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
Remplacez les éléments suivants :
- SUBSCRIPTION_ID : ID de l'abonnement à créer
- TOPIC_ID : ID du sujet à associer à l'abonnement
- FILTER : expression dans la syntaxe de filtrage
Pour créer un abonnement push avec un filtre, exécutez la commande gcloud pubsub subscriptions create
avec les options --push-endpoint
et --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
Remplacez les éléments suivants :
- SUBSCRIPTION_ID : ID de l'abonnement à créer
- TOPIC_ID : ID du sujet à associer à l'abonnement
- PUSH_ENDPOINT : URL du serveur sur lequel s'exécute l'abonné push
- FILTER : expression dans la syntaxe de filtrage
REST
Pour créer un abonnement avec un filtre, utilisez la méthode projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet dans lequel créer l'abonnement
- SUBSCRIPTION_ID : ID de l'abonnement à créer
Pour créer un abonnement pull avec un filtre, spécifiez le filtre dans le corps de la requête :
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet contenant le sujet.
- TOPIC_ID : ID du sujet à associer à l'abonnement
- FILTER : expression dans la syntaxe de filtrage
Pour créer un abonnement push avec un filtre, spécifiez le point de terminaison push et le filtre dans le corps de la requête :
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet contenant le sujet.
- TOPIC_ID : ID du sujet à associer à l'abonnement
- PUSH_ENDPOINT : URL du serveur sur lequel s'exécute l'abonné push
- FILTER : expression dans la syntaxe de filtrage
C++
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C++ qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C++.
C#
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C# qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C#.
Go
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Go qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.
Java
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Java qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Java.
Node.js
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Node.js.
Node.js
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Node.js.
PHP
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage PHP qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour PHP.
Python
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Python qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Python.
Ruby
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Ruby qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
La longueur maximale d'un filtre est de 256 octets. Le filtre est une propriété immuable d'un abonnement. Une fois l'abonnement créé, vous ne pouvez plus le mettre à jour pour modifier le filtre.
Impact des filtres sur les métriques de la file d'attente
Pour surveiller l'abonnement que vous venez de créer, consultez Surveiller les abonnements avec des filtres.
Si le filtrage est activé, les métriques de la file d'attente n'incluent que les données des messages correspondant au filtre. Voici la liste des métriques de la pile de demandes:
subscription/backlog_bytes
subscription/unacked_bytes_by_region
subscription/num_undelivered_messages
subscription/num_unacked_messages_by_region
subscription/oldest_unacked_message_age
subscription/oldest_unacked_message_age_by_region
topic/unacked_bytes_by_region
topic/num_unacked_messages_by_region
topic/oldest_unacked_messages_age_by_region
Pour en savoir plus sur ces métriques, consultez la liste des métriques Pub/Sub.
Modifier le filtre d'un abonnement
Vous ne pouvez pas modifier le filtre d'un abonnement existant. Suivez plutôt cette procédure de dépannage.
Prenez un instantané de l'abonnement pour lequel vous souhaitez modifier le filtre.
Pour en savoir plus sur la création d'un instantané à l'aide de la console, consultez Créer un instantané.
Créez un abonnement avec le nouveau filtre.
Pour en savoir plus sur la création d'un abonnement avec un filtre, consultez Créer un abonnement avec un filtre.
Dans la console Google Cloud, accédez à la page Abonnements Pub/Sub.
Cliquez sur l'abonnement que vous venez de créer.
Sur la page d'informations sur l'abonnement, cliquez sur Relire des messages.
Pour Rechercher, cliquez sur À un instantané.
Sélectionnez l'instantané que vous avez créé pour l'abonnement d'origine à l'étape 1, puis cliquez sur Seek (Rechercher).
Vous ne perdrez aucun message pendant la transition.
Modifiez les abonnements de tous les abonnés pour qu'ils utilisent le nouvel abonnement.
Une fois cette procédure terminée, vous pouvez supprimer l'abonnement d'origine.
Syntaxe permettant de créer un filtre
Pour filtrer les messages, écrivez une expression qui utilise des attributs. Vous pouvez écrire une expression qui correspond à la clé ou à la valeur des attributs. L'identifiant attributes
sélectionne les attributs du message.
Par exemple, les filtres du tableau suivant sélectionnent l'attribut name
:
Filtre | Description |
---|---|
attributes:name |
Messages comportant l'attribut name |
NOT attributes:name |
Messages sans attribut name |
attributes.name = "com" |
Messages avec l'attribut name et la valeur com |
attributes.name != "com" |
Messages sans l'attribut name et la valeur com |
hasPrefix(attributes.name, "co") |
Messages avec l'attribut name et une valeur commençant par co |
NOT hasPrefix(attributes.name, "co") |
Messages sans attribut name et une valeur commençant par co |
Opérateurs de comparaison pour l'expression de filtre
Vous pouvez filtrer les attributs à l'aide des opérateurs de comparaison suivants :
:
=
!=
L'opérateur :
correspond à une clé d'une liste d'attributs.
attributes:KEY
Les opérateurs d'égalité correspondent aux clés et aux valeurs. La valeur doit être une valeur littérale de chaîne.
attributes.KEY = "VALUE"
Une expression avec un opérateur d'égalité doit commencer par une clé, et l'opérateur doit comparer une clé et une valeur.
Valide : le filtre compare une clé et une valeur.
attributes.name = "com"
Non valide : le côté gauche du filtre est une valeur.
"com" = attributes.name
Non valide : le filtre compare deux clés.
attributes.name = attributes.website
La clé et la valeur sont sensibles à la casse et doivent correspondre exactement à l'attribut. Si une clé contient des caractères autres que des traits d'union, des traits de soulignement ou des caractères alphanumériques, utilisez un littéral de chaîne.
attributes."iana.org/language_tag" = "en"
Pour utiliser des barres obliques inverses, des guillemets et des caractères non imprimables dans un filtre, échappez les caractères dans un littéral de chaîne. Vous pouvez également utiliser des séquences d'échappement Unicode, hexadécimales et octales dans un littéral de chaîne.
Valide : le filtre échappe les caractères dans un littéral de chaîne.
attributes:"\u307F\u3093\u306A"
Non valide : le filtre échappe les caractères sans littéral de chaîne.
attributes:\u307F\u3093\u306A
Opérateurs booléens pour l'expression de filtre
Vous pouvez utiliser les opérateurs booléens AND
, NOT
et OR
dans un filtre. Les opérateurs doivent être en majuscules. Par exemple, le filtre suivant concerne les messages avec l'attribut iana.org/language_tag
, mais sans l'attribut name
et la valeur com
.
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
L'opérateur NOT
a la priorité la plus élevée. Pour combiner les opérateurs AND
et OR
, utilisez des parenthèses et des expressions complètes.
Valides : opérateurs
AND
etOR
avec des parenthèses.attributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
Non valide : opérateurs
AND
etOR
sans parenthèses.attributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
Non valide : les opérateurs
AND
etOR
combinent des expressions incomplètes.attributes.name = "com" AND ("net" OR "org")
Vous pouvez également utiliser l'opérateur moins unaire au lieu de l'opérateur NOT
.
attributes.name = "com" AND -attributes:"iana.org/language_tag"
Fonctions de l'expression de filtre
Vous pouvez utiliser la fonction hasPrefix
pour filtrer les attributs dont les valeurs commencent par une sous-chaîne. hasPrefix
est la seule fonction compatible dans un filtre.
Bien que la correspondance de préfixe soit compatible avec la fonction hasPrefix
, les expressions régulières générales ne le sont pas.
hasPrefix(attributes.KEY, "SUBSTRING")
Remplacez les éléments suivants :
- KEY : nom de l'attribut.
- SUBSTRING : sous-chaîne de la valeur