Ce document vous explique comment associer des schémas pour les sujets Pub/Sub.
Avant de commencer
- Comprendre le fonctionnement des schémas Pub/Sub
- Créez un schéma.
Rôles et autorisations requis
Pour obtenir les autorisations nécessaires pour associer et gérer des schémas, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor
) sur votre projet.
Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.
Ce rôle prédéfini contient les autorisations requises pour associer et gérer des schémas. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises
Les autorisations suivantes sont requises pour associer et gérer des schémas :
-
Créer un schéma :
pubsub.schemas.create
-
Associez le schéma au thème :
pubsub.schemas.attach
-
Valider une révision de schéma :
pubsub.schemas.commit
-
Supprimez un schéma ou une révision de schéma :
pubsub.schemas.delete
-
Obtenir un schéma ou des révisions de schéma :
pubsub.schemas.get
-
Lister les schémas :
pubsub.schemas.list
-
Lister les révisions de schéma :
pubsub.schemas.listRevisions
-
Effectuer un rollback d'un schéma :
pubsub.schemas.rollback
-
Validez un message :
pubsub.schemas.validate
-
Obtenez la stratégie IAM pour un schéma :
pubsub.schemas.getIamPolicy
-
Configurez la stratégie IAM pour un schéma :
pubsub.schemas.setIamPolicy
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Vous pouvez accorder des rôles et des autorisations à des comptes principaux tels que des utilisateurs, des groupes, des domaines ou des comptes de service. Vous pouvez créer un schéma dans un projet et l'associer à un sujet situé dans un autre projet. Assurez-vous de disposer des autorisations requises pour chaque projet.
Consignes pour associer un schéma à un sujet
Vous pouvez associer un schéma à un sujet lorsque vous créez ou modifiez un sujet. Voici les consignes à suivre pour associer un schéma à un sujet :
Vous pouvez associer un schéma à un ou plusieurs sujets.
Une fois qu'un schéma est associé à un sujet, chaque message que le sujet reçoit des éditeurs doit suivre ce schéma.
Lorsque vous associez un schéma à un sujet, vous devez également spécifier l'encodage des messages à publier sous la forme
BINARY
ouJSON
. Si vous utilisez JSON avec un schéma Avro, portez une attention particulière aux règles d'encodage pour les unions.Si un schéma associé à un sujet comporte des révisions, les messages doivent correspondre à l'encodage et être validés par rapport à une révision dans la plage disponible. Si la validation échoue, le message ne sera pas publié.
Les révisions sont testées dans l'ordre chronologique inverse de leur date de création. Pour créer une révision de schéma, consultez Valider une révision de schéma.
Logique de validation pour un schéma de message
Lorsque vous associez un schéma à un sujet et que le schéma comporte des révisions, vous pouvez spécifier une plage de révisions à utiliser. Si vous ne spécifiez pas de plage, la plage entière est utilisée pour la validation.
Si vous ne spécifiez pas de révision comme Première révision autorisée, la révision la plus ancienne existante pour le schéma est utilisée pour la validation. Si vous ne spécifiez pas de révision comme Dernière révision autorisée, la révision la plus récente du schéma est utilisée.
Prenons l'exemple du schéma S
associé au sujet T
.
Le schéma S
comporte les ID de révision A
, B
, C
et D
créés dans l'ordre, où A
est la première ou la plus ancienne révision. Aucun des schémas n'est identique à un autre ni à une restauration d'un schéma existant.
Si vous ne définissez que le champ Première révision autorisée sur
B
, les messages conformes uniquement au schémaA
sont refusés, tandis que les messages conformes aux schémasB
,C
etD
sont acceptés.Si vous ne définissez que le champ Dernière révision autorisée sur
C
, les messages conformes aux schémasA
,B
etC
sont acceptés, et les messages conformes uniquement au schémaD
sont refusés.Si vous définissez les deux champs Première révision autorisée sur
B
et Dernière révision autorisée surC
, les messages conformes aux schémasB
etC
sont acceptés.Vous pouvez également définir la première et la dernière révision sur le même ID de révision. Dans ce cas, seuls les messages conformes à cette révision sont acceptés.
Créer et associer un schéma lorsque vous créez un sujet
Vous pouvez créer un sujet avec un schéma à l'aide de la console Google Cloud , de gcloud CLI, de l'API Pub/Sub ou des bibliothèques clientes Cloud.
Console
Dans la console Google Cloud , accédez à la page Sujets Pub/Sub.
Cliquez sur Create topic (Créer un sujet).
Dans le champ ID du sujet, saisissez un ID pour votre sujet.
Pour savoir comment nommer un sujet, consultez les consignes.
Cochez la case Utiliser un schéma.
Conservez les paramètres par défaut pour les autres champs.
Vous pouvez créer un schéma ou en utiliser un existant.
Si vous créez un schéma, procédez comme suit : `
- Dans le champ Sélectionner un schéma Pub/Sub, sélectionnez Créer un schéma.
La page Créer un schéma s'affiche dans un onglet secondaire.
Suivez la procédure décrite dans Créer un schéma.
Revenez à l'onglet Créer un sujet, puis cliquez sur Actualiser.
Recherchez votre schéma dans le champ Sélectionner un schéma Pub/Sub.
Sélectionnez l'encodage du message : JSON ou Binary.
Le schéma que vous venez de créer possède un ID de révision. Vous pouvez créer des révisions de schéma supplémentaires, comme indiqué dans Valider une révision de schéma.
Si vous associez un schéma déjà créé, procédez comme suit :
Dans le champ Sélectionner un schéma Pub/Sub, sélectionnez un schéma existant.
Sélectionnez l'encodage du message : JSON ou Binary.
Facultatif : Si le schéma sélectionné comporte des révisions, utilisez les menus déroulants Première révision autorisée et Dernière révision autorisée pour Plage de révisions.
Vous pouvez spécifier les deux champs, n'en spécifier qu'un seul ou conserver les paramètres par défaut en fonction de vos besoins.
Conservez les paramètres par défaut pour les autres champs.
Cliquez sur Créer pour enregistrer le thème et l'attribuer au schéma sélectionné.
gcloud
Pour créer un sujet auquel est attribué un schéma créé précédemment, exécutez la commande gcloud pubsub topics create
:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Où :
- TOPIC_ID correspond à l'ID du sujet que vous créez.
- ENCODING_TYPE correspond à l'encodage des messages validés par rapport au schéma. Cette valeur doit être définie sur
JSON
ouBINARY
. - SCHEMA_ID correspond à l'ID d'un schéma existant.
- FIRST_REVISION_ID est l'ID de la révision la plus ancienne à valider.
- LAST_REVISION_ID est l'ID de la dernière révision à valider.
--first-revision-id
et --last-revision-id
sont facultatifs.
Vous pouvez également attribuer un schéma à partir d'un autre projet Google Cloud :
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
Où :
- SCHEMA_PROJECT est l'ID de projet du projet Google Cloud pour le schéma.
- TOPIC_PROJECT est l'ID de projet du projet Google Cloud pour le thème.
REST
Pour créer un sujet, utilisez la méthode projects.topics.create
:
Requête :
La demande doit être authentifiée à l'aide d'un jeton d'accès dans l'en-tête Authorization
. Pour obtenir un jeton d'accès pour les identifiants par défaut actuels de l'application, exécutez la commande suivante : gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corps de la requête :
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
Où :
- PROJECT_ID est l'ID de votre projet.
- TOPIC_ID est l'ID de votre sujet.
- SCHEMA_NAME est le nom du schéma par rapport auquel les messages publiés doivent être validés. Il a le format suivant :
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE correspond à l'encodage des messages validés par rapport au schéma. Cette valeur doit être définie sur
JSON
ouBINARY
. - FIRST_REVISION_ID est l'ID de la révision la plus ancienne à valider.
- LAST_REVISION_ID est l'ID de la dernière révision à valider.
firstRevisionId
et lastRevisionId
sont facultatifs.
Réponse :
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
et lastRevisionId
sont tous deux omis s'ils ne sont pas fournis dans la requête.
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.
Modifier un schéma associé à un sujet
Vous pouvez modifier un sujet pour y associer un schéma, le supprimer ou mettre à jour la plage de révisions utilisée pour valider les messages. En général, si vous prévoyez de modifier le schéma utilisé, vous pouvez valider une nouvelle révision et mettre à jour la plage de révisions utilisée pour la rubrique.
Vous pouvez modifier un schéma associé à un sujet à l'aide de la consoleGoogle Cloud , de la gcloud CLI, de l'API Pub/Sub ou des bibliothèques clientes Cloud.
Console
Dans la console Google Cloud , accédez à la page Sujets Pub/Sub.
Cliquez sur l'ID de sujet d'un sujet.
Sur la page des détails de la rubrique, cliquez sur Modifier.
Vous pouvez apporter les modifications suivantes au schéma.
La prise en compte des modifications peut prendre quelques minutes.
Si vous souhaitez supprimer le schéma du sujet, sur la page Modifier le sujet, décochez la case Utiliser un schéma.
Si vous souhaitez modifier le schéma, sélectionnez le nom d'un schéma dans la section Schéma.
Mettez à jour les autres champs si nécessaire.
- Si vous souhaitez modifier la plage de révisions, utilisez les menus déroulants Première révision autorisée et Dernière révision autorisée sous Plage de révisions.
Vous pouvez spécifier les deux champs, n'en spécifier qu'un seul ou conserver les paramètres par défaut en fonction de vos besoins.
Cliquez sur Mettre à jour pour enregistrer les modifications.
gcloud
gcloud pubsub topics update TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_NAME \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Où :
- TOPIC_ID correspond à l'ID du sujet que vous créez.
- ENCODING_TYPE correspond à l'encodage des messages validés par rapport au schéma. Cette valeur doit être définie sur
JSON
ouBINARY
. - SCHEMA_NAME correspond au nom d'un schéma existant.
- FIRST_REVISION_ID est l'ID de la révision la plus ancienne à valider.
- LAST_REVISION_ID est l'ID de la dernière révision à valider.
--first-revision-id
et --last-revision-id
sont facultatifs.
REST
Pour mettre à jour un sujet, utilisez la méthode projects.topics.patch
:
Requête :
La demande doit être authentifiée à l'aide d'un jeton d'accès dans l'en-tête Authorization
. Pour obtenir un jeton d'accès pour les identifiants par défaut actuels de l'application, exécutez la commande suivante : gcloud auth application-default print-access-token
.
PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corps de la requête :
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" "update_mask": } }
Où :
- PROJECT_ID est l'ID de votre projet.
- TOPIC_ID est l'ID de votre sujet.
- SCHEMA_NAME est le nom du schéma par rapport auquel les messages publiés doivent être validés. Il a le format suivant :
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE correspond à l'encodage des messages validés par rapport au schéma. Cette valeur doit être définie sur
JSON
ouBINARY
. - FIRST_REVISION_ID est l'ID de la révision la plus ancienne à valider.
- LAST_REVISION_ID est l'ID de la dernière révision à valider.
firstRevisionId
et lastRevisionId
sont facultatifs.
Réponse :
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
et lastRevisionId
ne sont pas définis après la mise à jour.
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.
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.
Étapes suivantes
- Valider une révision de schéma
- Publier des messages dans un sujet avec un schéma
- Valider une définition de schéma
- Valider un message pour un schéma