Ce document vous explique comment associer des schémas aux sujets Pub/Sub.
Avant de commencer
- Découvrez 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
-
Associer le schéma au sujet :
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
-
Répertorier les schémas:
pubsub.schemas.list
-
Liste des révisions de schéma :
pubsub.schemas.listRevisions
-
Effectuer un rollback d'un schéma :
pubsub.schemas.rollback
-
Valider un message :
pubsub.schemas.validate
-
Obtenez la stratégie IAM d'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 le créez ou le modifiez. 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 en tant que
BINARY
ouJSON
. Si vous utilisez du JSON avec un schéma Avro, veillez à respecter les 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 de la plage disponible. Si elles ne le font pas, la publication du message échoue.
Les révisions sont essayées dans l'ordre chronologique inverse, en fonction de l'heure de création. Pour créer une révision de schéma, consultez Validez 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 un sous-ensemble de révisions à utiliser. Si vous ne spécifiez pas de plage, l'ensemble de la plage est utilisé pour la validation.
Si vous ne définissez pas de révision sur Première révision autorisée, alors la révision la plus ancienne du schéma est utilisée pour la validation. Si vous ne définissez pas de révision comme Dernière révision autorisée, alors la révision existante la plus récente pour le schéma est utilisée.
Prenons l'exemple du schéma S
associé au sujet T
.
Les ID de révision A
, B
, C
et D
du schéma S
sont créés dans l'ordre.
où A
correspond à la première ou à la plus ancienne révision. Aucun des schémas n'est identique aux autres ni n'est un rollback d'un schéma existant.
Si vous définissez uniquement le champ Première révision autorisée sur
B
, les messages conformes uniquement au schémaA
sont rejeté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 rejeté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 la CLI gcloud, 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 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 utiliser un schéma 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 et cliquez sur Actualiser.
Recherchez votre schéma dans le champ Sélectionner un schéma Pub/Sub.
Sélectionnez l'encodage du message en tant que JSON ou Binary (Binaire).
Le schéma que vous venez de créer possède un ID de révision. Vous pouvez créer d'autres révisions de schéma, comme indiqué dans la section 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 en tant que JSON ou Binary (Binaire).
Facultatif : Si le schéma sélectionné comporte des révisions, pour Plage de révisions, utilisez les menus déroulants Première révision autorisée et Dernière révision autorisée.
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 exigences.
Conservez les paramètres par défaut pour les autres champs.
Cliquez sur Créer pour enregistrer le sujet et l'attribuer au schéma sélectionné.
gcloud
Pour créer un sujet associé à 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 vis-à-vis de la
du schéma. Cette valeur doit être définie sur
JSON
ouBINARY
. - SCHEMA_ID correspond à l'ID d'un schéma existant.
- FIRST_REVISION_ID correspond à l'ID de la plus ancienne révision à valider.
- LAST_REVISION_ID correspond à 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 du projet Google Cloud pour le schéma.
- TOPIC_PROJECT est l'ID du projet Google Cloud associé au sujet.
REST
Pour créer un sujet, utilisez la méthode projects.topics.create
.
méthode:
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. Le format est le suivant:
projects/PROJECT_ID/schemas/SCHEMA_ID
- ENCODING_TYPE est l'encodage des messages validés par rapport au schéma. Il doit être défini sur
JSON
ouBINARY
. - FIRST_REVISION_ID correspond à l'ID de la plus ancienne révision à valider.
- LAST_REVISION_ID correspond à 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" } }
Les champs firstRevisionId
et lastRevisionId
sont omis s'ils ne sont pas fournis
dans la demande.
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 joindre un schéma, en supprimer un ou mettre à jour la plage de révisions utilisée pour valider les messages. En général, si vous avez prévu des modifications pour le schéma utilisé, vous pouvez commettre une nouvelle révision et mettre à jour la plage de révisions utilisée pour le sujet.
Vous pouvez modifier un schéma associé à un sujet à l'aide de la console Google Cloud, de la CLI gcloud, 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 d'informations du thème, cliquez sur Modifier.
Vous pouvez apporter les modifications suivantes au schéma.
L'application 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 mettre à jour la plage de révisions, pour Plage de révisions, utilisez les menus déroulants pour Première révision autorisée et Dernière révision autorisée.
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 exigences.
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 à utiliser pour la validation.
- LAST_REVISION_ID correspond à l'ID de la dernière révision à valider.
--first-revision-id
et --last-revision-id
sont facultatifs.
REST
Pour mettre à jour un thème, utilisez la méthode projects.topics.patch
méthode:
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. Le format est le suivant:
projects/PROJECT_ID/schemas/SCHEMA_ID
- ENCODING_TYPE est l'encodage des messages validés par rapport au schéma. Il doit être défini sur
JSON
ouBINARY
. - FIRST_REVISION_ID correspond à l'ID de la plus ancienne révision à valider.
- LAST_REVISION_ID correspond à 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 le
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.
0Étape suivante
- Valider une révision de schéma
- Publier des messages dans un sujet à l'aide d'un schéma
- Valider une définition de schéma
- Valider un message pour un schéma