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

Facultatif. Immuable. 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 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 la création d'un abonnement. Sinon, il ne s'agit que de la sortie. Un ou plusieurs types d'événements à recevoir concernant la ressource cible. Mise en forme conforme à 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 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. Disponible uniquement pour les événements Google Chat.

notificationEndpoint

object (NotificationEndpoint)

Obligatoire. Immuable. Point de terminaison sur lequel 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 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. 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 et peut être envoyée lors des demandes de mise à jour afin de s'assurer que le client dispose d'une valeur à jour avant de continuer.

Champ d'union expiration. 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ées dans le champ PayloadOptions):

  • Si les charges utiles omettent les données de ressource, jusqu'à sept jours.
  • Jusqu'à quatre heures si les charges utiles incluent des données de ressources. 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 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)

La valeur par défaut n'est pas vide. Code temporel en UTC de l'expiration de l'abonnement. Toujours affiché en sortie, quelle que soit la fonction 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 aucune valeur n'est spécifiée ou si elle est 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. 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 qui a été 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, 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 d'un message Google Chat et l'heure de création, saisissez message.sender,message.createTime. Si cette valeur 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 sur lequel l'abonnement envoie 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 où 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 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 distribuer des événements au point de terminaison de ses notifications.
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 autorisé a révoqué l'autorisation d'un ou 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'est pas autorisée à envoyer des é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 des notifications de l'abonnement n'a pas pu recevoir d'événements en raison d'un quota insuffisant ou d'un dépassement de la 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

Récupère les détails d'un abonnement Google Workspace.

list

Répertorie les abonnements Google Workspace.

patch

Met à jour ou renouvelle un abonnement Google Workspace.

reactivate

Réactive un abonnement Google Workspace suspendu.