REST Resource: subscriptions

Ressource : Subscription

Abonnement permettant de recevoir des événements sur 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

Facultatif. Immuable. Identifiant. Nom de ressource de l'abonnement.

Format : subscriptions/{subscription}
uid

string

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

string

Obligatoire. Immuable. Ressource Google Workspace surveillée pour les événements, présentée sous la forme du nom complet de la ressource. Pour en savoir plus sur les ressources cibles et les événements compatibles, consultez Événements Google Workspace compatibles.

Un utilisateur ne peut autoriser votre application qu'à créer 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. Immuable. Liste à puces. Entrée pour créer un abonnement. Sinon, uniquement en sortie. Un ou plusieurs types d'événements à recevoir concernant la ressource cible. Formaté conformément à la spécification CloudEvents.

Les types d'événements compatibles 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 sur 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 disponible pour les événements Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Obligatoire. Immuable. Point de terminaison sur lequel 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 des notifications.
suspensionReason

enum (ErrorType)

Uniquement en sortie. Erreur qui a suspendu l'abonnement.

Pour réactiver l'abonnement, corrigez 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 de Google Workspace, la valeur {user} correspond au champ user.id de l'API Directory.
createTime

string (Timestamp format)

Uniquement en sortie. Date et 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 d'autres champs. Elle peut être envoyée lors des demandes de mise à jour pour s'assurer que le client dispose d'une valeur à jour avant de poursuivre.

Champ d'union expiration. Date et heure d'expiration de l'abonnement.

Le délai d'expiration maximal varie selon que votre abonnement inclut ou non des données de ressources dans les charges utiles d'événement (spécifié dans le champ PayloadOptions):

  • Si les charges utiles omettent les données de ressources, cela peut prendre 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 au niveau du domaine, vous pouvez prolonger le délai d'expiration de l'abonnement jusqu'à 24 heures.

Lorsqu'un abonnement expire, il est automatiquement supprimé. Vous recevez les é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 des événements de cycle de vie et y répondre.

Pour éviter qu'un abonnement n'expire, vous pouvez reporter sa date d'expiration à l'aide de la méthode UpdateSubscription. 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. Toujours affiché en sortie, quelle que soit la valeur utilisée 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 définie sur 0, utilise la durée maximale possible.

PayloadOptions

Options concernant les données à inclure dans la charge utile de l'événement. Uniquement disponible 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 qui a été modifiée. Par exemple, pour un événement dans lequel un message Google Chat a été créé, 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, il s'agit de 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. En cas d'omission, 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 sur lequel 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 Cloud Pub/Sub qui reçoit les événements pour l'abonnement.

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

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

Lorsque le sujet reçoit des événements, ceux-ci sont encodés en tant que messages Cloud Pub/Sub. Pour en savoir plus, consultez 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 transmettre 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 concernant un abonnement.

Enums
ERROR_TYPE_UNSPECIFIED Valeur par défaut. Cette valeur n'est pas utilisée.
USER_SCOPE_REVOKED L'utilisateur responsable a révoqué l'autorisation 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 aux événements pour envoyer les événements au point de terminaison des notifications de votre abonnement.
ENDPOINT_NOT_FOUND Le point de terminaison de notification de l'abonnement n'existe pas, ou il 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 limitation du 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.