REST Resource: subscriptions

リソースのサブスクリプション

Google Workspace リソースに関するイベントを受信するためのサブスクリプション。サブスクリプションの詳細については、Google Workspace Events API の概要をご覧ください。

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 authority_info can be only one of the following:
  "userAuthority": string,
  "serviceAccountAuthority": string
  // End of list of possible types for union field authority_info.

  // Union field authority_info can be only one of the following:
  "userAuthority": string,
  "serviceAccountAuthority": string
  // End of list of possible types for union field authority_info.

  "expireTime": string,
  "ttl": string
}
フィールド
name

string

ID。サブスクリプションのリソース名。

形式: subscriptions/{subscription}
uid

string

出力専用。システムによって割り当てられたサブスクリプションの一意の識別子。
targetResource

string

必須。変更不可。イベントをモニタリングする Google Workspace リソース。完全なリソース名としてフォーマットされます。ターゲット リソースとサポートされているイベントについては、サポートされている Google Workspace イベントをご覧ください。

ユーザーは、特定のターゲット リソースに対して 1 つのサブスクリプションを作成する権限のみをアプリに付与できます。アプリが同じユーザー認証情報で別のサブスクリプションを作成しようとすると、リクエストは ALREADY_EXISTS エラーを返します。
eventTypes[]

string

必須。順序なしリスト。サブスクリプションを作成するための入力。それ以外の場合は出力専用。ターゲット リソースに関するイベントを受信する 1 つ以上のタイプ。CloudEvents 仕様に従ってフォーマットされます。

サポートされているイベントタイプは、サブスクリプションのターゲット リソースによって異なります。詳しくは、サポートされている Google Workspace イベントをご覧ください。

デフォルトでは、サブスクリプションのライフサイクルに関するイベントも受信します。このフィールドにライフサイクル イベントを指定する必要はありません。

ターゲット リソースに存在しないイベントタイプを指定すると、リクエストは HTTP 400 Bad Request ステータス コードを返します。
payloadOptions

object (PayloadOptions)

省略可。イベント ペイロードに含めるデータに関するオプション。Google Chat イベントでのみサポートされます。
notificationEndpoint

object (NotificationEndpoint)

必須。変更不可。サブスクリプションがイベントを配信するエンドポイント（Pub/Sub トピックなど）。
state

enum (State)

出力専用。サブスクリプションの状態。サブスクリプションがイベントを受信して通知エンドポイントに配信できるかどうかを決定します。
suspensionReason

enum (ErrorType)

出力専用。サブスクリプションを停止したエラー。

サブスクリプションを再度有効にするには、エラーを解決して subscriptions.reactivate メソッドを呼び出します。
authority

string

出力専用。サブスクリプションの作成を承認したユーザー。

ユーザーがサブスクリプションを承認すると、このフィールドと userAuthority フィールドの値は同じになり、形式は次のようになります。

形式: users/{user}

Google Workspace ユーザーの場合、{user} 値は user.id フィールドです。

Chat アプリがサブスクリプションを承認すると、serviceAccountAuthority フィールドのみが入力され、このフィールドは空になります。
共用体フィールド authority_info。サブスクリプションの作成を承認した ID。authority_info は次のいずれかになります。
userAuthority

string

出力専用。サブスクリプションの作成を承認したユーザー。ユーザーは targetResource を表示できる必要があります。

Google Workspace ユーザーの場合、{user} 値は user.id フィールドです。

形式: users/{user}
serviceAccountAuthority

string

出力専用。サブスクリプションの作成を承認するために使用されたサービス アカウント。このサービス アカウントは、このサブスクリプションを作成した Google Cloud プロジェクトと同じプロジェクトが所有している必要があります。

形式: projects/{projectId}/serviceAccounts/{service_account_id}
createTime

string (Timestamp format)

出力専用。サブスクリプションが作成された時刻。
updateTime

string (Timestamp format)

出力専用。サブスクリプションが最後に更新された時刻。
reconciling

boolean

出力専用。true の場合、サブスクリプションは更新中です。
etag

string

省略可。このチェックサムは、他のフィールドの値に基づいてサーバーによって計算されます。これは、更新リクエストで送信され、続行する前にクライアントが最新の値を持っていることを確認できます。

共用体フィールド expiration。サブスクリプションの有効期限。

最大有効期限は、サブスクリプションのイベント ペイロードにリソースデータが含まれているかどうかによって異なります（PayloadOptions フィールドで指定）。

  • ペイロードでリソースデータが省略されている場合は、最長 7 日間。
  • ペイロードにリソースデータが含まれている場合は、最長 4 時間。Google Workspace 組織が ドメイン全体の委任によってリソースへのアクセスを許可している場合は、サブスクリプションの有効期限を最長 24 時間まで延長できます。

サブスクリプションは、有効期限が切れると自動的に削除されます。サブスクリプションの有効期限が切れる 12 時間前と 1 時間前に、ライフサイクル イベントが notification_endpoint に送信されます。詳しくは、ライフサイクル イベントを受信して対応するをご覧ください。

サブスクリプションの有効期限が切れないようにするには、UpdateSubscription メソッドを使用して有効期限を延長します。詳しくは、サブスクリプションを更新または更新するをご覧ください。expiration は次のいずれかになります。
expireTime

string (Timestamp format)

空でないデフォルト。サブスクリプションの有効期限が切れるときのタイムスタンプ（UTC）。入力で使用されたものに関係なく、出力に常に表示されます。
ttl

string (Duration format)

入力専用。サブスクリプションの有効期間（TTL）。指定しない場合、または 0 に設定した場合は、可能な限り最長の期間が使用されます。

PayloadOptions

イベント ペイロードに含めるデータに関するオプション。Google Chat イベントでのみサポートされます。

JSON 表現 
{
  "includeResource": boolean,
  "fieldMask": string
}
フィールド
includeResource

boolean

省略可。イベント ペイロードに変更されたリソースに関するデータが含まれるかどうか。たとえば、Google Chat メッセージが作成されたイベントの場合、ペイロードに Message リソースに関するデータが含まれるかどうか。false の場合、イベント ペイロードには変更されたリソースの名前のみが含まれます。
fieldMask

string (FieldMask format)

省略可。includeResource が true に設定されている場合は、イベント ペイロードに含めるフィールドのリスト。フィールドはカンマで区切ります。たとえば、Google Chat メッセージの送信者と作成時刻を含めるには、message.sender,message.createTime と入力します。省略すると、ペイロードにはリソースのすべてのフィールドが含まれます。

リソースに存在しないフィールドを指定すると、そのフィールドは無視されます。

NotificationEndpoint

サブスクリプションがイベントを配信するエンドポイント。

JSON 表現 
{

  "pubsubTopic": string
}
フィールド

共用体フィールド endpoint。

endpoint は次のいずれかになります。
pubsubTopic

string

変更不可。サブスクリプションのイベントを受信する Pub/Sub トピック。

形式: projects/{project}/topics/{topic}

このサブスクリプションを作成する Google Cloud プロジェクトと同じプロジェクトにトピックを作成する必要があります。

注: Google Workspace Events API は、順次イベントのために順序指定キーを使用します。Cloud Pub/Sub トピックに、最も近い Google Cloud リージョンを除外するように メッセージ ストレージ ポリシーが構成されている場合、順序指定キーを使用してイベントを公開すると失敗します。

トピックがイベントを受信すると、イベントは Pub/Sub メッセージとしてエンコードされます。詳しくは、CloudEvents の Google Cloud Pub/Sub プロトコル バインディングをご覧ください。

州名

サブスクリプションが取り得る状態。

列挙型
STATE_UNSPECIFIED デフォルト値。この値は使用されません。
ACTIVE サブスクリプションは有効で、イベントを受信して通知エンドポイントに配信できます。
SUSPENDED エラーのため、サブスクリプションはイベントを受信できません。エラーを特定するには、suspensionReason フィールドをご覧ください。
DELETED サブスクリプションは削除されます。

ErrorType

サブスクリプションで発生する可能性のあるエラー。

列挙型
ERROR_TYPE_UNSPECIFIED デフォルト値。この値は使用されません。
USER_SCOPE_REVOKED 承認ユーザーが 1 つ以上の OAuth スコープの権限を取り消しました。Google Workspace の承認について詳しくは、OAuth 同意画面を構成するをご覧ください。
APP_SCOPE_REVOKED ドメイン管理者がアプリの 1 つ以上の OAuth スコープの権限を取り消しました。
RESOURCE_DELETED サブスクリプションのターゲット リソースが存在しなくなりました。
USER_AUTHORIZATION_FAILURE サブスクリプションの作成を承認したユーザーが、サブスクリプションのターゲット リソースにアクセスできなくなりました。
APP_AUTHORIZATION_FAILURE サブスクリプションの作成を承認したアプリが、サブスクリプションのターゲット リソースにアクセスできなくなりました。
ENDPOINT_PERMISSION_DENIED Google Workspace アプリケーションには、サブスクリプションの通知エンドポイントにイベントを配信する権限がありません。
ENDPOINT_NOT_FOUND サブスクリプションの通知エンドポイントが存在しないか、サブスクリプションを作成した Google Cloud プロジェクトでエンドポイントが見つかりません。
ENDPOINT_RESOURCE_EXHAUSTED 割り当てが不足しているか、レート制限に達したため、サブスクリプションの通知エンドポイントでイベントを受信できませんでした。
OTHER 不明なエラーが発生しました。

メソッド

create

 Google Workspace サブスクリプションを作成します。

delete

 Google Workspace サブスクリプションを削除します。

get

 Google Workspace サブスクリプションの詳細を取得します。

list

 Google Workspace サブスクリプションを一覧表示します。

patch

 Google Workspace サブスクリプションを更新または更新します。

reactivate

 停止中の Google Workspace サブスクリプションを再度有効にします。