REST Resource: subscriptions

Ressource : Subscription

Abonnement permettant de recevoir des événements concernant une ressource Google Workspace. Pour en savoir plus sur les abonnements, consultez la présentation de l'API Google Workspace Events.

Représentation JSON 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Champs
name

string

Identifiant. Nom de ressource de l'abonnement.

Format : subscriptions/{subscription}
uid

string

Uniquement en sortie. Identifiant unique attribué par le système pour l'abonnement.
targetResource

string

Obligatoire. Immuable. Ressource Google Workspace surveillée pour les événements, au format nom complet de la ressource. Pour en savoir plus sur les ressources cibles et les événements qu'elles prennent en charge, consultez Événements Google Workspace compatibles.

Un utilisateur ne peut autoriser votre application à créer qu'un seul abonnement pour une ressource cible donnée. Si votre application tente de créer un autre abonnement avec les mêmes identifiants utilisateur, la requête renvoie une erreur ALREADY_EXISTS.
eventTypes[]

string

Obligatoire. Liste à puces. Entrée pour la création d'un abonnement. Sinon, sortie uniquement. Un ou plusieurs types d'événements à recevoir concernant la ressource cible. Formaté selon la spécification CloudEvents.

Les types d'événements acceptés dépendent de la ressource cible de votre abonnement. Pour en savoir plus, consultez Événements Google Workspace compatibles.

Par défaut, vous recevez également des événements concernant le cycle de vie de votre abonnement. Vous n'avez pas besoin de spécifier d'événements de cycle de vie pour ce champ.

Si vous spécifiez un type d'événement qui n'existe pas pour la ressource cible, la requête renvoie un code d'état HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

Facultatif. Options concernant les données à inclure dans la charge utile de l'événement. Uniquement compatible avec les événements Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Obligatoire. Immuable. Point de terminaison où l'abonnement fournit des événements, comme un sujet Pub/Sub.
state

enum (State)

Uniquement en sortie. État de l'abonnement. Détermine si l'abonnement peut recevoir des événements et les transmettre au point de terminaison de notification.
suspensionReason

enum (ErrorType)

Uniquement en sortie. Erreur ayant entraîné la suspension de l'abonnement.

Pour réactiver l'abonnement, résolvez l'erreur et appelez la méthode subscriptions.reactivate.
authority

string

Uniquement en sortie. Utilisateur qui a autorisé la création de l'abonnement.

Format : users/{user}

Pour les utilisateurs Google Workspace, la valeur {user} correspond au champ user.id de l'API Directory.
createTime

string (Timestamp format)

Uniquement en sortie. Heure de création de l'abonnement.
updateTime

string (Timestamp format)

Uniquement en sortie. Date de la dernière mise à jour de l'abonnement.
reconciling

boolean

Uniquement en sortie. Si la valeur est true, l'abonnement est en cours de modification.
etag

string

Facultatif. Cette somme de contrôle est calculée par le serveur en fonction de la valeur des autres champs. Elle peut être envoyée dans les demandes de mise à jour pour s'assurer que le client dispose d'une valeur à jour avant de continuer.

Champ d'union expiration. Heure d'expiration de l'abonnement.

La durée d'expiration maximale dépend de la présence ou non de données de ressources dans les charges utiles d'événement de votre abonnement (spécifiées dans le champ PayloadOptions) :

  • Si les charges utiles omettent les données de ressources : jusqu'à sept jours.
  • Si les charges utiles incluent des données de ressources : jusqu'à quatre heures. Si votre organisation Google Workspace accorde l'accès à la ressource via la délégation à l'échelle du domaine, vous pouvez prolonger la durée d'expiration de l'abonnement jusqu'à 24 heures.

Une fois l'abonnement expiré, il est automatiquement supprimé. Vous recevez des événements de cycle de vie pour notification_endpoint 12 heures et une heure avant l'expiration de l'abonnement. Pour en savoir plus, consultez Recevoir et traiter les événements du cycle de vie.

Pour empêcher l'expiration d'un abonnement, vous pouvez utiliser la méthode UpdateSubscription afin de prolonger sa date d'expiration. Pour en savoir plus, consultez Mettre à jour ou renouveler un abonnement. La expiration ne peut être qu'un des éléments suivants :
expireTime

string (Timestamp format)

Valeur par défaut non vide. Horodatage en UTC de l'expiration de l'abonnement. Il est toujours affiché en sortie, quel que soit le code utilisé en entrée.
ttl

string (Duration format)

Uniquement en entrée. Durée de vie (TTL) ou durée de l'abonnement. Si elle n'est pas spécifiée ou définie sur 0, la durée maximale possible est utilisée.

PayloadOptions

Options concernant les données à inclure dans la charge utile de l'événement. Uniquement compatible avec les événements Google Chat.

Représentation JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
Champs
includeResource

boolean

Facultatif. Indique si la charge utile de l'événement inclut des données sur la ressource qui a été modifiée. Par exemple, pour un événement de création d'un message Google Chat, indique si la charge utile contient des données sur la ressource Message. Si la valeur est "false", la charge utile de l'événement n'inclut que le nom de la ressource modifiée.
fieldMask

string (FieldMask format)

Facultatif. Si includeResource est défini sur true, la liste des champs à inclure dans la charge utile de l'événement. Séparez les champs par une virgule. Par exemple, pour inclure l'expéditeur et l'heure de création d'un message Google Chat, saisissez message.sender,message.createTime. Si ce paramètre est omis, la charge utile inclut tous les champs de la ressource.

Si vous spécifiez un champ qui n'existe pas pour la ressource, le système l'ignore.

NotificationEndpoint

Point de terminaison où l'abonnement fournit des événements.

Représentation JSON 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
Champs

Champ d'union endpoint.

endpoint ne peut être qu'un des éléments suivants :
pubsubTopic

string

Immuable. Sujet Pub/Sub qui reçoit les événements pour l'abonnement.

Format : projects/{project}/topics/{topic}

Vous devez créer le sujet dans le même projet Google Cloud que celui dans lequel vous créez cet abonnement.

Remarque : L'API Google Workspace Events utilise des clés de tri pour les événements séquentiels. Si le sujet Cloud Pub/Sub est configuré avec une règle de stockage des messages qui exclut la région Google Cloud la plus proche, la publication d'événements avec des clés de tri échouera.

Lorsque le sujet reçoit des événements, ils sont encodés en tant que messages Pub/Sub. Pour en savoir plus, consultez Google Cloud Pub/Sub Protocol Binding for CloudEvents.

État

États possibles de l'abonnement.

Enums
STATE_UNSPECIFIED Valeur par défaut. Cette valeur n'est pas utilisée.
ACTIVE L'abonnement est actif et peut recevoir et distribuer des événements à son point de terminaison de notification.
SUSPENDED L'abonnement ne peut pas recevoir d'événements en raison d'une erreur. Pour identifier l'erreur, consultez le champ suspensionReason.
DELETED L'abonnement est supprimé.

ErrorType

Erreurs possibles pour un abonnement.

Enums
ERROR_TYPE_UNSPECIFIED Valeur par défaut. Cette valeur n'est pas utilisée.
USER_SCOPE_REVOKED L'utilisateur ayant accordé l'autorisation a révoqué l'attribution d'un ou de plusieurs champs d'application OAuth. Pour en savoir plus sur l'autorisation pour Google Workspace, consultez Configurer l'écran de consentement OAuth.
RESOURCE_DELETED La ressource cible de l'abonnement n'existe plus.
USER_AUTHORIZATION_FAILURE L'utilisateur qui a autorisé la création de l'abonnement n'a plus accès à la ressource cible de l'abonnement.
ENDPOINT_PERMISSION_DENIED L'application Google Workspace n'a pas accès au point de terminaison de notification de votre abonnement pour y envoyer des événements.
ENDPOINT_NOT_FOUND Le point de terminaison de notification de l'abonnement n'existe pas ou est introuvable dans le projet Google Cloud dans lequel vous avez créé l'abonnement.
ENDPOINT_RESOURCE_EXHAUSTED Le point de terminaison de notification de l'abonnement n'a pas reçu d'événements en raison d'un quota insuffisant ou de l'atteinte d'une limite de débit.
OTHER Une erreur non identifiée s'est produite.

Méthodes

create

 Crée un abonnement Google Workspace.

delete

 Supprime un abonnement Google Workspace.

get

 Obtient des informations sur un abonnement Google Workspace.

list

 Liste les abonnements Google Workspace.

patch

 Met à jour ou renouvelle un abonnement Google Workspace.

reactivate

 Réactive un abonnement Google Workspace suspendu.