プッシュ通知

このドキュメントでは、プッシュ通知を使用して、 アプリケーションを変更する必要はありません。

概要

Admin SDK API のプッシュ通知を使用して、 おすすめします。この機能を使用すると、キャンペーンの 説明します。これにより、余分なネットワークやコンピューティング リソースを リソースのポーリングに関連するコストも削減できます。 監視対象のリソースが変更されるたびに、Admin SDK API は 説明します。

プッシュ通知を使用するには、次の 2 つのことを行う必要があります。

  • 受信 URL(Webhook)を設定するコールバック レシーバとして渡されます。

    この 通知メッセージを処理する HTTPS サーバーです。 トリガーされます。

  • 必要なリソース エンドポイントごとに(通知チャンネル)を設定する 。

    チャネルは通知のルーティング情報を指定する ブロックすることもできます。チャネル設定の一環として、そのチャネルの URL を を選択します。チャンネルのリソースが変更されると Admin SDK API が通知メッセージを POST として送信します。 リクエストをその URL に送信します。

現在、Admin SDK API では、 Activities リソース。

通知チャンネルを作成する

プッシュ通知をリクエストするには、通知チャンネルを設定する必要があります リソースごとに最大 100 個の IP アドレスが必要です。通知チャンネルを設定した後 Admin SDK API は、監視対象のリソースが検出されたときに できます。

監視のリクエストを行う

監視可能な各 Admin SDK API リソースには、 次の形式の URI で watch メソッドを使用します。

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

アプリケーションの変更に関するメッセージの通知チャンネルを設定するには、 POST リクエストを リソースの watch メソッド。

各通知チャンネルは特定のユーザーとユーザーの両方に 特定のリソース(またはリソースセット)へのアクセスを制御します。watch リクエスト ログインするには、現在のユーザーが またはサービス アカウント このリソースへのアクセス権を持ちます。

アクティビティ リソースの監視リクエストはすべて、一般的な形式になります。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

userKeyapplicationNameeventNamefilters パラメータを使用すると、特定のイベント、ユーザー、アプリの通知のみを受け取ることができます。

注: 次の例では、わかりやすくするためにリクエスト本文を省略しています。

すべての管理アクティビティに注意する:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

ドキュメントのすべてのアクティビティを監視する:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

特定ユーザーの管理アクティビティを監視する:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

ユーザーのパスワード変更など、特定のイベントを監視します。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

特定のドキュメントに対する変更を監視します。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

必須プロパティ

watch リクエストで、次のフィールドを指定する必要があります。

  • これを一意に識別する id プロパティ文字列 通知チャンネルを作成します。Google Cloud コンソールの ユニバーサルな固有識別子 (UUID)など 使用します。最大文字数: 64 文字。

    設定した ID 値が すべての通知の X-Goog-Channel-Id HTTP ヘッダー メッセージが届きます。

  • 値に設定された type プロパティ文字列 web_hook

  • リッスンする URL に設定された address プロパティ文字列 この通知チャンネルの通知に応答します。これは、 HTTPS を使用する必要があります。

    なお、Admin SDK API は、 有効な SSL 証明書がインストールされている場合にのみ、この HTTPS アドレスを使用できます。 作成します。次のような証明書は無効です。

    • 自己署名証明書。
    • 信頼できない提供元によって署名された証明書。
    • 失効した証明書。
    • ターゲットと一致しないサブジェクトを持つ証明書 使用します。

省略可能なプロパティ

これらのオプション フィールドを、 watch リクエスト:

  • 任意の文字列を指定する token プロパティ 値を渡します。通知チャンネルを使用すると、 使用できます。たとえば、 認証トークンを使用して、各受信メッセージが 作成され、通知が送信されていないことを または、メールを内部の正しい宛先に このチャネルの目的に応じてアプリケーションを設計します。最大文字数: 256 文字。

    トークンは すべての通知の X-Goog-Channel-Token HTTP ヘッダー アプリケーションがこのチャンネル用に受信するメッセージです。

    通知チャンネル トークンを使用する場合は、次のことをおすすめします。

    • URL クエリなどの拡張可能なエンコード形式を使用する あります。例: forwardTo=hr&createdBy=mobile

    • OAuth トークンなどのセンシティブ データは含めないでください。

    で確認できます。
  • 設定された expiration プロパティ文字列。 Unix タイムスタンプ (ミリ秒単位)です。 この通知チャンネルへのメッセージの送信を停止します。

    チャネルに有効期限がある場合は、 X-Goog-Channel-Expiration HTTP ヘッダー(人が読める形式) すべての通知メッセージに 受信するメッセージの数を表します。

で確認できます。

リクエストの詳細については、watch メソッドをご覧ください。 API リファレンスの Activities リソースをご覧ください。

スマートウォッチのレスポンス

watch リクエストによって通知が正常に作成された場合 HTTP 200 OK ステータス コードを返します。

ウォッチ レスポンスのメッセージ本文には、メッセージの 通知チャンネルを使用します。

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

リクエストの一部として送信したプロパティに加えて、 返される情報には、resourceIdresourceUri で監視対象のリソースを識別 通知チャンネル。

返された情報を他の通知チャンネルに渡すことができます。 受信を停止したいときなどのオペレーションを できます

レスポンスの詳細については、watch を参照してください。 API リファレンスの Activities リソースのメソッドをご覧ください。

メッセージを同期

リソースを監視する通知チャンネルを作成すると、 Admin SDK API が sync メッセージを送信して、 通知が開始されます。X-Goog-Resource-State HTTP これらのメッセージのヘッダー値は sync です。ネットワークが原因で タイミングに問題がある場合、sync メッセージを受信する可能性があります。 watchメソッドのレスポンスを受け取る前でもかまいません

sync の通知は無視してもかまいませんが、 使用しています。たとえば、特定のメッセージを保持せずに 作成するには、X-Goog-Channel-ID と 呼び出し内の X-Goog-Resource-ID の値 通知の受信を停止します。また、 初期化を行うための sync 通知 できます。

Admin SDK API が送信する sync メッセージの形式 受信側の URL は次のとおりです。

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

同期メッセージには常に X-Goog-Message-Number HTTP が含まれる 1 のヘッダー値。このチャンネルの後続の通知には、 メッセージ番号が前のものよりも大きくなりますが、 番号は連続しません。

通知チャンネルを更新する

通知チャンネルには、有効期限とその値 リクエストまたは Admin SDK API の内部制限によって決定されます またはデフォルト(より制限の厳しい値が使用されます)チャンネルの有効期限 時刻がある場合は、Unix タイムスタンプとして含めます。 (ミリ秒単位)。watch メソッドによって返される情報。また、 有効期限の日時を人間が読み取れる形式で このチャネルに関してアプリケーションが受信する通知メッセージを X-Goog-Channel-Expiration HTTP ヘッダー。

現時点では、通知チャンネルを自動的に更新する方法はありません。日時 チャネルの有効期限が近づいている場合は、次を呼び出して新しいチャネルに置き換える必要があります。 watch メソッドを使用します。他のケースと同様に、名前には一意の値を使用する必要があります。 新しいチャンネルの id プロパティ。なお、 「重なり」であると言えます。2 つの通知チャンネルが通知される期間を 同じリソースがアクティブになります。

通知を受け取る

監視対象のリソースが変更されると、アプリケーションは 変更を説明する通知メッセージが送信されます。Admin SDK API はこれらの情報を HTTPS POST リクエストとして、 この通知の address プロパティ

通知メッセージの形式を解釈する

すべての通知メッセージには、一連の HTTP ヘッダーが X-Goog- 接頭辞。 通知の種類によっては、 あります。

ヘッダー

Admin SDK API によって受信側に送信された通知メッセージ URL には次の HTTP ヘッダーを含めます。

ヘッダー 説明
常に表示
X-Goog-Channel-ID この ID を識別するために指定した UUID またはその他の一意の文字列 通知チャンネル。
X-Goog-Message-Number この通知のメッセージを識別する整数 。sync メッセージの場合、値は常に 1 です。メッセージ 後続のメッセージの数が増えますが 順序ではありません。
X-Goog-Resource-ID 監視対象のリソースを識別する不透明な値。この ID は API バージョン間で安定している。
X-Goog-Resource-State 通知をトリガーした新しいリソースの状態。 可能な値: sync またはイベント名
X-Goog-Resource-URI 監視対象リソースの API バージョン固有の識別子。
ときどき存在する
X-Goog-Channel-Expiration 通知チャンネルの有効期限( 記述できます。定義されている場合のみ存在します。
X-Goog-Channel-Token アプリケーションによって設定された通知チャンネル トークン 通知ソースの確認に使用できます。次の場合にのみ表示 定義します。

アクティビティの通知メッセージのリクエスト本文には、次の情報が含まれます。

プロパティ 説明
kind これを Activity リソースとして識別します。値: 固定文字列 "admin#reports#activity"。
id アクティビティ レコードの一意の識別子。
id.time アクティビティの発生時刻。値の ISO 8601 の日付と時刻の形式。時間 は、完全な日付、時、分、秒を YYYY-MM-DDThh:mm:ssTZD の形式で表したものです。 例: 2010-04-05T17:30:04+01:00
id.uniqueQualifier 複数のイベントの時間が同じ場合の一意の修飾子。
id.applicationName イベントが属するアプリケーション名。有効な値は次のとおりです。 <ph type="x-smartling-placeholder">
id.customerId Google Workspace アカウントの一意の識別子。
actor アクションを行うユーザー。
actor.callerType レポートに記載されているアクティビティを行った作成者のタイプ。このバージョンの API では、callerType は、レポートにリストされているアクションを実行した USER または OAuth 2LO エンティティ リクエストです。
actor.email アクティビティが報告されるユーザーのメインのメールアドレス。
actor.profileId ユーザーの一意の Google Workspace プロファイル ID。
ownerDomain 管理コンソールのドメイン、またはドキュメント アプリケーションのドキュメントのオーナー。これは、レポートのイベントの影響を受けるドメインです。
ipAddress アクションを行ったユーザーの IP アドレス。これは、Google Workspace にログインする際のユーザーのインターネット プロトコル(IP)アドレスです。ユーザーの物理的な場所を反映しているとは限りません。たとえば、ユーザーのプロキシ サーバーのアドレスや、バーチャル プライベート ネットワーク(VPN)のアドレスを IP アドレスとして使用できます。API は IPv4IPv6 をサポートしています。
events[] レポートのアクティビティ イベント。
events[].type イベントの種類。管理者によって変更される Google Workspace のサービスまたは機能は、eventName プロパティを使用してイベントを識別する type プロパティで識別されます。
events[].name イベントの名前。これは、API によってレポートされるアクティビティの具体的な名前です。各 eventName は特定の Google Workspace サービスまたは機能に関連付けられており、API によってイベントの種類別に整理されます。
eventName リクエスト パラメータの概要は次のとおりです。 <ph type="x-smartling-placeholder">
    </ph>
  • eventName が指定されていない場合、レポートは eventName に該当する可能性があるすべてのインスタンスを返します。
  • eventName をリクエストすると、API のレスポンスはその eventName を含むすべてのアクティビティを返します。返されるアクティビティには、リクエストしたプロパティに加えて、他の eventName プロパティが存在する可能性があります。
events[].parameters[] さまざまなアプリケーションに対応するパラメータ値のペア。
events[].parameters[].name パラメータの名前。
events[].parameters[].value パラメータの文字列値。
events[].parameters[].intValue パラメータの整数値。
events[].parameters[].boolValue パラメータのブール値。

アクティビティ リソース イベントの通知メッセージの一般的な形式は次のとおりです。

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

管理アクティビティ イベントの例:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

お知らせに対応する

成功を示すために、次のいずれかのステータス コードが返されます。 200201202204、または 102

サービスが Google の API クライアント ライブラリを使用している場合 Admin SDK API の 500502503、または 504 を返します。 指数バックオフによる再試行。 それ以外の戻りステータス コードは、すべてメッセージ失敗とみなされます。

Admin SDK API の通知イベントについて

このセクションでは、送信できる通知メッセージの詳細を 受信するプッシュ通知の数を確認します。

Reports API のプッシュ通知には、同期メッセージとイベント通知の 2 種類のメッセージが含まれます。メッセージ タイプは X-Goog-Resource-State HTTP ヘッダーに示されます。イベント通知に指定できる値は、activities.list メソッドの場合と同じです。アプリケーションごとに固有のイベントがあります。

通知を停止する

expiration プロパティは、通知を自動的に停止するタイミングを制御します。Google Chat では 通知を受け取らないように設定することもできます。 次の URL にある stop メソッドを呼び出して期限切れにします。 次の URI を使用します。

https://www.googleapis.com/admin/reports_v1/channels/stop

この方法では、少なくともチャンネルの id プロパティと resourceId プロパティ。次のサンプルをご覧ください。 見てみましょう。Admin SDK API に複数の種類のタグがある場合は、 watch メソッドを持つリソースは 1 つだけ stop メソッドを使用します。

チャンネルの停止は、適切な権限を持つユーザーのみが行えます。具体的には、次のとおりです。

  • チャンネルが通常のユーザー アカウントで作成された場合は、 の OAuth 2.0 クライアント ID で識別されるよう、同じクライアントから 認証トークンなど)を使用して、そのチャンネルを停止できます。
  • チャンネルがサービス アカウントによって作成された場合、同じサービスの クライアントがチャネルを停止できます。

次のコードサンプルは、通知の受信を停止する方法を示しています。

POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}