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 à 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 acceptent, consultez la section É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 non ordonnée. Données pour créer un abonnement. Sinon, sortie uniquement. Un ou plusieurs types d'événements à recevoir concernant la ressource cible. Formaté conformément à 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 la section Événements Google Workspace compatibles.

Par défaut, vous recevez également les é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. Compatible uniquement avec les événements Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Obligatoire. Immuable. Point de terminaison où l'abonnement envoie des événements, par exemple 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 suspendu l'abonnement.

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

string

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

Format : users/{user}

Pour les utilisateurs de 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 mise à jour.
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 lors des requêtes de mise à jour pour s'assurer que le client dispose d'une valeur à jour avant de continuer.

Champ d'union expiration. Date et 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 (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 une délégation au niveau du domaine, vous pouvez prolonger la date d'expiration de l'abonnement jusqu'à 24 heures.

Lorsqu'un abonnement expire, il est automatiquement supprimé. Vous recevez des événements de cycle de vie dans notification_endpoint 12 heures et une heure avant l'expiration de l'abonnement. Pour en savoir plus, consultez Recevoir et répondre aux événements de cycle de vie.

Pour éviter l'expiration d'un abonnement, vous pouvez utiliser la méthode UpdateSubscription pour repousser 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. Code temporel en UTC de l'expiration de l'abonnement. Toujours affiché en sortie, quel que soit ce qui a été utilisé en entrée.
ttl

string (Duration format)

Uniquement en entrée. Valeur TTL (Time To Live) ou durée de l'abonnement. Si elle n'est pas spécifiée ou si elle est 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. Disponible uniquement pour 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 modifiée. Par exemple, pour un événement où un message Google Chat a été créé, la charge utile contient-elle 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, 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 elle est omise, 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 diffuse 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 Cloud Pub/Sub qui reçoit les événements de l'abonnement.

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

Vous devez créer le sujet dans le projet Google Cloud où vous créez cet abonnement.

Lorsque le sujet reçoit des événements, ils sont encodés en tant que messages Cloud Pub/Sub. Pour en savoir plus, consultez la section Liaison de protocole Google Cloud Pub/Sub pour 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 diffuser des événements vers 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 autorisé l'accès 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 à l'envoi d'événements au point de terminaison de notification de votre abonnement.
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 pu recevoir d'événements en raison d'un quota insuffisant ou d'une limite de débit atteinte.
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

 Récupère les informations sur un abonnement Google Workspace.

list

 Liste les abonnements Google Workspace.

patch

 Mise à jour ou renouvellement d'un abonnement Google Workspace

reactivate

 Réactive un abonnement Google Workspace suspendu.