Google Workspace サブスクリプションを作成する

このページでは、Google Workspace Events API を使用して Google Workspace リソースのサブスクリプションを作成する方法について説明します。Google Workspace サブスクリプションを使用すると、Google Workspace リソースの変更を表す Google Workspace イベントに関する情報をアプリで受信できます。Google Workspace Events API がサポートするリソースとイベントタイプについては、Google Workspace Events API の概要をご覧ください。

このページでは、Google Workspace サブスクリプションを作成する手順について説明します。

  1. 環境を設定する。
  2. Google Cloud Pub/Sub トピックを作成してサブスクライブする。このトピックを Google Workspace イベントを受信するためのエンドポイントとして使用します。
  3. Subscription リソースの Google Workspace Events API の create() メソッドを呼び出します。
  4. Google Workspace サブスクリプションをテストして、登録したイベントを Pub/Sub トピックが受信することを確認します。
  5. 必要に応じて、アプリがイベントを処理し、必要に応じてアクションを実行できるように、アプリのエンドポイントにイベントをプッシュする方法を構成します。

前提条件

Apps Script

  • このガイドの Google Cloud CLI コマンドを使用するには:
    1. Google Cloud CLI をインストールします。
    2. gcloud CLI を 初期化するには、次のコードを実行します。
      3.   gcloud init
  • 定期購入のターゲット リソース:
    • Google Chat スペースに登録するには、認証されたユーザーがメンバーである Chat スペースが必要です。ユーザーは、Google Workspace または Google アカウントを使用してスペースのメンバーである必要があります（Google グループを介したスペースのメンバーはサポートされていません）。
    • Google Meet 会議スペースに登録するには、認証されたユーザーがオーナーとなる会議スペースが必要です。スペースを作成するには、Google Meet ドキュメントの会議スペースを管理するをご覧ください。
    • Google Meet ユーザーを登録するには、Cloud Identity API の user ID
  • 課金が有効になっている Google Cloud プロジェクト。Chat に登録する場合は、Cloud プロジェクトで Chat API を有効にし、[アプリ名]、[アバター URL]、[説明] の各フィールドを構成する必要があります。詳しくは、Google Chat アプリを作成するをご覧ください。
  • アプリに構成された OAuth 同意画面でユーザー認証が必要です。同意画面を構成する際には、定期購入の各イベントタイプをサポートするスコープを指定する必要があります。同意画面を設定して必要なスコープを特定するには、スコープの選択をご覧ください。
  • Apps Script プロジェクト:
    • Apps Script によって自動的に作成されるデフォルトのプロジェクトではなく、Google Cloud プロジェクトを使用します。
    • OAuth 同意画面を構成するために追加したスコープについては、Apps Script プロジェクトの appsscript.json ファイルにスコープを追加する必要があります。次に例を示します。 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.readonly"
]
    • Google Workspace Events 拡張サービスを有効にします。

Python

  • Python 3.6 以降
  • pip パッケージ管理ツール
  • Python 用の最新の Google クライアント ライブラリ。これらをインストールまたは更新するには、コマンドライン インターフェースで次のコマンドを実行します。 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • このガイドの Google Cloud CLI コマンドを使用するには:
    1. Google Cloud CLI をインストールします。
    2. gcloud CLI を 初期化するには、次のコードを実行します。
      3.   gcloud init
  • 定期購入のターゲット リソース:
    • Google Chat スペースに登録するには、認証されたユーザーがメンバーである Chat スペースが必要です。ユーザーは、Google Workspace または Google アカウントを使用してスペースのメンバーである必要があります（Google グループを介したスペースのメンバーはサポートされていません）。
    • Google Meet 会議スペースに登録するには、認証されたユーザーがオーナーとなる会議スペースが必要です。スペースを作成するには、Google Meet ドキュメントの会議スペースを管理するをご覧ください。
    • Google Meet ユーザーを登録するには、Cloud Identity API の user ID
  • 課金が有効になっている Google Cloud プロジェクト。Chat に登録する場合は、Cloud プロジェクトで Chat API を有効にし、[アプリ名]、[アバター URL]、[説明] の各フィールドを構成する必要があります。詳しくは、Google Chat アプリを作成するをご覧ください。
  • アプリに構成された OAuth 同意画面でユーザー認証が必要です。同意画面を構成する際には、定期購入の各イベントタイプをサポートするスコープを指定する必要があります。同意画面を設定して必要なスコープを特定するには、スコープの選択をご覧ください。

環境を設定する

次のセクションでは、Google Workspace サブスクリプションを作成する前に環境を設定する方法について説明します。

Google Workspace Events API と Google Cloud Pub/Sub API を有効にする

Google API を使用する前に、Google Cloud プロジェクトで API を有効にする必要があります。1 つの Google Cloud プロジェクトで 1 つ以上の API を有効にできます。

Google Cloud コンソール

Google Cloud コンソールでアプリの Google Cloud プロジェクトを開き、Google Workspace Events API と Pub/Sub API を有効にします。

API を有効にする

gcloud

  1. 作業ディレクトリで、Google アカウントにログインします。

    gcloud auth login

  2. プロジェクトをアプリの Cloud プロジェクトに設定します。

    gcloud config set project PROJECT_ID

    PROJECT_ID は、アプリの Cloud プロジェクトのプロジェクト ID に置き換えます。

  3. Google Workspace Events API と Google Cloud Pub/Sub API を有効にします。

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

OAuth クライアント ID の認証情報を作成する

OAuth クライアント ID の作成手順については、該当するアプリケーションの種類を選択してください。

ウェブ アプリケーション

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [ウェブ アプリケーション] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. アプリに関連する承認済み URI を追加します。
    • クライアントサイド アプリ（JavaScript） - [承認済みの JavaScript 生成元] で [URI を追加] をクリックします。次に、ブラウザ リクエストに使用する URI を入力します。アプリケーションが OAuth 2.0 サーバーに API リクエストを送信できるドメインを指定します。
    • サーバーサイド アプリ（Java、Python など） - [承認済みのリダイレクト URI] で、[URI を追加] をクリックします。次に、OAuth 2.0 サーバーがレスポンスを送信できるエンドポイント URI を入力します。
  6. [作成] をクリックします。[OAuth クライアントの作成] 画面に、新しいクライアント ID とクライアント シークレットが表示されます。

    クライアント ID をメモします。クライアント シークレットはウェブ アプリケーションには使用されません。

  7. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] に表示されます。

Android

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [Android] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. [Package name]（パッケージ名）フィールドに、AndroidManifest.xml ファイルのパッケージ名を入力します。
  6. [SHA-1 証明書フィンガープリント] に、生成した SHA-1 証明書フィンガープリントを入力します。
  7. [作成] をクリックします。[OAuth クライアントの作成] 画面に、新しいクライアント ID が表示されます。
  8. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] の下に表示されます。

iOS

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [iOS] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. [バンドル ID] に、アプリの Info.plist ファイルに記載されているバンドル ID を入力します。
  6. 省略可: アプリが Apple App Store に表示されている場合は、App Store ID を入力します。
  7. 省略可: [チーム ID] フィールドに、Apple によって生成され、チームに割り当てられた一意の 10 文字の文字列を入力します。
  8. [作成] をクリックします。[OAuth クライアントの作成] 画面が表示され、新しいクライアント ID とクライアント シークレットが表示されます。
  9. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] の下に表示されます。

Chrome アプリ

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [Chrome アプリ] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. [アプリケーション ID] に、アプリ固有の 32 文字の ID 文字列を入力します。この ID の値は、アプリの Chrome ウェブストア URL と Chrome ウェブストア デベロッパー ダッシュボードで確認できます。
  6. [作成] をクリックします。[OAuth クライアントの作成] 画面が表示され、新しいクライアント ID とクライアント シークレットが表示されます。
  7. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] の下に表示されます。

デスクトップ アプリ

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [デスクトップ アプリ] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. [作成] をクリックします。[OAuth クライアントの作成] 画面が表示され、新しいクライアント ID とクライアント シークレットが表示されます。
  6. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] に表示されます。

テレビ、入力制限のあるデバイス

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [テレビと入力制限のあるデバイス] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. [作成] をクリックします。[OAuth クライアントの作成] 画面が表示され、新しいクライアント ID とクライアント シークレットが表示されます。
  6. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] の下に表示されます。

ユニバーサル Windows プラットフォーム（UWP）

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. [アプリケーションの種類] > [ユニバーサル Windows プラットフォーム（UWP）] をクリックします。
  4. [名前] フィールドに、認証情報の名前を入力します。この名前は Google Cloud コンソールにのみ表示されます。
  5. [ストア ID] に、アプリに固有の 12 文字の Microsoft Store ID 値を入力します。この ID は、アプリの Microsoft Store URL とパートナー センターで確認できます。
  6. [作成] をクリックします。[OAuth クライアントの作成] 画面が表示され、新しいクライアント ID とクライアント シークレットが表示されます。
  7. [OK] をクリックします。新しく作成された認証情報が [OAuth 2.0 クライアント ID] の下に表示されます。

クライアント シークレットの JSON ファイルをダウンロードする

クライアント シークレット ファイルは、アプリが認証情報を提供するときに参照できる OAuth クライアント ID の認証情報の JSON 表現です。

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [認証情報] に移動します。

    [認証情報] に移動

  2. [OAuth 2.0 クライアント ID] で、作成したクライアント ID をクリックします。

  3. [JSON をダウンロード] をクリックします。

  4. ファイルを client_secrets.json として保存します。

Pub/Sub トピックを作成してサブスクライブする

このセクションでは、Pub/Sub トピックとトピックへのサブスクリプションを作成します。Pub/Sub トピックは、Google Workspace サブスクリプションがイベントを受信する通知エンドポイントとして機能します。

Pub/Sub トピックの作成と管理の詳細については、Pub/Sub のドキュメントをご覧ください。

Pub/Sub トピックを作成してサブスクライブするには:

Google Cloud コンソール

  1. Google Cloud コンソールで、[Pub/Sub] ページに移動します。

    Google Cloud Pub/Sub に移動

    アプリの Cloud プロジェクトが選択されていることを確認します。

  2. [ トピックを作成] をクリックして、次の操作を行います。

    1. トピックの名前を入力します（例: workspace-events-topic）。
    2. [デフォルトのサブスクリプションを追加] を選択したままにします。Pub/Sub は、このデフォルト サブスクリプションにトピックの名前と同様の名前を付けます（例: workspace-events-topic-sub）。
    3. 省略可: トピックの追加のプロパティを更新または構成します。

  3. [作成] をクリックします。完全なトピック名の形式は projects/PROJECT_ID/topics/TOPIC_ID です。このフルネームは後のステップで使用します。

  4. Pub/Sub メッセージをトピックにパブリッシュするためのアクセス権を付与します。

    1. トピックのページでサイドパネルに移動し、[権限] タブを開きます。
    2. [プリンシパルを追加] をクリックします。
    3. [プリンシパルを追加] フィールドに、サブスクリプションにイベントを配信する Google Workspace アプリケーションのサービス アカウントを追加します。
      1. Chat イベントの場合は、chat-api-push@system.gserviceaccount.com。
      2. Meet のイベントの場合は、meet-api-event-push@system.gserviceaccount.com。
    4. [ロールの割り当て] メニューで、Pub/Sub Publisher を選択します。
    5. [保存] をクリックします。トピックの権限が更新されるまでに数分かかることがあります。

gcloud

  1. Cloud プロジェクトで、次のコマンドを実行してトピックを作成します。

    gcloud pubsub topics create TOPIC_ID

    TOPIC_ID は、トピックの一意の ID（workspace-events-topic など）に置き換えます。

    出力には、完全なトピック名が projects/PROJECT_ID/topics/TOPIC_ID の形式で表示されます。名前をメモし、PROJECT_ID の値がアプリの Cloud プロジェクト ID であることを確認します。トピック名は次のステップで使用して、後で Google Workspace サブスクリプションを作成します。

  2. トピックにメッセージをパブリッシュするためのアクセス権を付与します。

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

    次のように置き換えます。

    • TOPIC_NAME: 完全なトピック名。前の手順の出力です。形式は projects/PROJECT_ID/topics/TOPIC_ID です。

    • GOOGLE_WORKSPACE_APPLICATION: サブスクリプションにイベントを配信する必要がある Google Workspace アプリケーション。

      • Chat からイベントを受信するには、chat-api-push@system.gserviceaccount.com を使用します。
      • Meet からイベントを受信するには、meet-api-event-push@system.gserviceaccount.com を使用します。

    トピックの権限が更新されるまでに数分かかることがあります。

  3. トピックに Pub/Sub サブスクリプションを作成します。

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

    次のように置き換えます。

    • SUBSCRIPTION_NAME: サブスクリプションの名前（workspace-events-subscription など）。
    • TOPIC_NAME: 前の手順で作成したトピックの名前。

Google Workspace サブスクリプションを作成する

このセクションでは、Google Workspace Events API の subscriptions.create() メソッドを使用して Subscription リソースを作成します。次のフィールドを指定します。

  • targetResource: Chat スペースなどのイベントをモニタリングする Google Workspace リソース。
  • eventTypes: リソースに関して受信する 1 つ以上のイベントタイプの配列。たとえば、Chat スペースに投稿された新しいメッセージについてのみアプリが知る必要がある場合、アプリは作成されたメッセージに関するイベントにサブスクライブするだけで済みます。
  • notificationEndpoint: Google Workspace サブスクリプションがイベントを配信する通知エンドポイント。前のセクションで作成した Pub/Sub トピックを使用します。
  • payloadOptions: イベント ペイロードに含めるリソースデータの量を指定するオプション。この構成は、サブスクリプションの有効期限に影響します。詳しくは、イベントデータをご覧ください。

Google Workspace サブスクリプションを作成するには:

Apps Script

  1. Apps Script プロジェクトで、createSubscription という名前の新しいスクリプト ファイルを作成し、次のコードを追加します。

    function createSubscription() {
  // The Google Workspace resource to monitor for events.
  const targetResource = 'TARGET_RESOURCE';

  // The types of events to receive.
  const eventTypes = [EVENT_TYPES];

  // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  const pubsubTopic = 'TOPIC_NAME';

  // Whether to include resource data or not.
  const resourceData = RESOURCE_DATA;

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.create({
    targetResource: targetResource,
    eventTypes: eventTypes,
    notificationEndpoint: {
      pubsubTopic: pubsubTopic,
    },
    payloadOptions: {
      includeResource: resourceData
    }
  });
  console.log(response);
}

    次のように置き換えます。

    • TARGET_RESOURCE: 登録している Google Workspace リソース（完全なリソース名の形式）。たとえば、スペース ID が AAAABBBB の Google Chat スペースに登録するには、//chat.googleapis.com/spaces/AAAABBBB を使用します。
    • EVENT_TYPES: ターゲット リソースで登録する 1 つ以上のイベントタイプ。'google.workspace.chat.message.v1.created' などの文字列の配列としてフォーマットします。
    • TOPIC_NAME: Cloud プロジェクトで作成した Pub/Sub トピックの完全な名前。形式は projects/PROJECT_ID/topics/TOPIC_ID です。

    • RESOURCE_DATA: サブスクリプションのペイロードにリソースデータを含めるかどうかを指定するブール値。

      • True: すべてのリソースデータが含まれます。含まれるフィールドを制限するには、fieldMask フィールドを追加し、変更されたリソースのフィールドを 1 つ以上指定します。リソースデータを含むチャット リソースをサポートするのは、Chat リソースのサブスクリプションのみです。
      • False: リソースデータを除外します。

  2. Google Workspace サブスクリプションを作成するには、Apps Script プロジェクトで関数 createSubscription を実行します。

Python

  1. 作業ディレクトリに create_subscription.py という名前のファイルを作成し、次のコードを追加します。

    """Create subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('client_secrets.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# The Google Workspace resource to monitor for events.
TARGET_RESOURCE = 'TARGET_RESOURCE'

# The types of events to receive.
EVENT_TYPES = [EVENT_TYPES]

# The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}
response = service.subscriptions().create(body=BODY).execute()
print(response)

    次のように置き換えます。

    • SCOPES: 定期購入の各イベントタイプをサポートする 1 つ以上の OAuth スコープ。文字列の配列としてフォーマットされます。複数のスコープを一覧表示するには、カンマで区切ります。例: 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'
    • TARGET_RESOURCE: 登録している Google Workspace リソース（完全なリソース名の形式）。たとえば、スペース ID が AAAABBBB の Google Chat スペースに登録するには、//chat.googleapis.com/spaces/AAAABBBB を使用します。
    • EVENT_TYPES: ターゲット リソースで登録する 1 つ以上のイベントタイプ。'google.workspace.chat.message.v1.created' などの文字列の配列としてフォーマットします。
    • TOPIC_NAME: Cloud プロジェクトで作成した Pub/Sub トピックの完全な名前。形式は projects/PROJECT_ID/topics/TOPIC_ID です。

    • RESOURCE_DATA: サブスクリプションのペイロードにリソースデータを含めるかどうかを指定するブール値。

      • True: すべてのリソースデータが含まれます。含まれるフィールドを制限するには、fieldMask フィールドを追加し、変更されたリソースのフィールドを 1 つ以上指定します。リソースデータを含むチャット リソースをサポートするのは、Chat リソースのサブスクリプションのみです。
      • False: リソースデータを除外します。

  2. Google Workspace サブスクリプションを作成するには、ターミナルで次のコマンドを実行します。

    python3 create_subscription.py

Google Workspace Events API は、作成した Subscription リソースのインスタンスを含む完了した長時間実行オペレーションを返します。

Google Workspace サブスクリプションをテストする

Google Workspace イベントを受信していることをテストするには、イベントをトリガーし、Pub/Sub サブスクリプションにメッセージを pull します。

Google Workspace サブスクリプションをテストするには:

Google Cloud コンソール

  1. Google Workspace サブスクリプションのターゲット リソースで 1 つ以上のタイプのイベントをトリガーします。たとえば、Chat スペースで新しいメッセージに登録している場合は、スペースにメッセージを投稿します。

  2. Google Cloud コンソールで、[Pub/Sub] ページに移動します。

    [Pub/Sub] に移動

    アプリの Cloud プロジェクトが選択されていることを確認します。

  3. [Pub/Sub] メニューで、[サブスクリプション] をクリックします。

  4. 表内で、トピックの Pub/Sub サブスクリプションを見つけて、サブスクリプション名をクリックします。

  5. [メッセージ] タブをクリックします。

  6. [Pull] をクリックします。イベントが Pub/Sub メッセージを生成するまでに数分かかることがあります。

gcloud

  1. Google Workspace サブスクリプションのターゲット リソースで 1 つ以上のタイプのイベントをトリガーします。たとえば、Chat スペースで新しいメッセージに登録している場合は、スペースにメッセージを投稿します。

  2. 次のコマンドを実行します。

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

    次のように置き換えます。

    • PUBSUB_SUBSCRIPTION_NAME: Pub/Sub サブスクリプションの完全な名前（projects/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID 形式）。
    • MESSAGE_COUNT: pull する Pub/Sub メッセージの最大数。

    イベントが Pub/Sub メッセージを生成するまでに数分かかることがあります。

トリガーした Google Workspace イベントごとに、そのイベントを含む Pub/Sub サブスクリプションにメッセージが配信されます。詳しくは、イベントを Google Cloud Pub/Sub メッセージとして受信するをご覧ください。

アプリがイベントを受信する方法を構成する

作成した Pub/Sub サブスクリプションは pull ベースです。Pub/Sub サブスクリプションをテストしたら、配信タイプを更新して、アプリがイベントを受信する方法を変更できます。たとえば、アプリがアプリ エンドポイントに直接イベントを受信できるように、Pub/Sub サブスクリプションを push 配信タイプに構成できます。

Pub/Sub サブスクリプションの構成については、Pub/Sub のドキュメントをご覧ください。