プッシュ通知

必須プロパティ

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

• プロジェクト内のこの新しい通知チャンネルを一意に識別する id プロパティ文字列。UUID（Universally Unique Identifier）または同様の一意の文字列を使用することをおすすめします。最大文字数: 64 文字。

  設定した ID 値は、このチャンネルで受信するすべての通知メッセージの X-Goog-Channel-Id HTTP ヘッダーにエコーバックされます。

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

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

  Admin SDK API からこの HTTPS アドレスに通知を送信できるのは、ウェブサーバーに有効な SSL 証明書がインストールされている場合のみです。次のような証明書は無効です。

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

省略可能なプロパティ

watch リクエストで次のオプション フィールドを指定することもできます。

• チャネル トークンとして使用する任意の文字列値を指定する token プロパティ。通知チャンネル トークンはさまざまな目的で使用できます。たとえば、トークンを使用して、各受信メッセージがアプリケーションによって作成されたチャネルのものであることを確認できます。これにより、通知のなりすましを防止できます。また、このチャネルの目的に基づいて、アプリケーション内の適切な宛先にメッセージをルーティングすることもできます。最大長: 256 文字。

  このトークンは、アプリケーションがこのチャネルについて受け取るすべての通知メッセージの X-Goog-Channel-Token HTTP ヘッダーに含まれます。

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

  • URL クエリ パラメータなど、拡張可能なエンコード形式を使用します。例: forwardTo=hr&createdBy=mobile

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

• Admin SDK API がこの通知チャネルのメッセージ送信を停止する日時の Unix タイムスタンプ（ミリ秒単位）に設定された expiration プロパティ文字列。

  チャネルに有効期限が設定されている場合、アプリケーションがこのチャネルについて受信するすべての通知メッセージに、X-Goog-Channel-Expiration HTTP ヘッダー（人が読める形式）の値として含まれます。

ウォッチのレスポンス

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.
}

リクエストの一部として送信したプロパティに加えて、返される情報には resourceId と resourceUri も含まれます。これにより、この通知チャンネルで監視されているリソースを識別できます。

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

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

メッセージを同期する

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

sync 通知は無視してかまいませんが、使用することもできます。たとえば、チャンネルを保持しない場合は、呼び出しで X-Goog-Channel-ID と X-Goog-Resource-ID の値を使用して通知の受信を停止できます。また、sync 通知を使用して初期化を行い、後のイベントに備えることもできます。

Admin SDK API が受信 URL に送信する sync メッセージの形式を以下に示します。

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 の内部上限またはデフォルト（より制限の厳しい値が使用されます）によって決定されます。チャネルの有効期限（設定されている場合）は、watch メソッドから返される情報に Unix タイムスタンプ（ミリ秒単位）として含まれています。また、有効期限の日付と時刻は、アプリがこのチャネルについて受け取るすべての通知メッセージの X-Goog-Channel-Expiration HTTP ヘッダーに、人が読める形式で記載されます。

現在のところ、通知チャンネルを自動的に更新する方法はありません。チャネルの有効期限が近づいたら、watch メソッドを呼び出して、チャネルを新しいチャネルに置き換える必要があります。通常どおり、新しいチャンネルの id プロパティには一意の値を使用する必要があります。同じリソースの 2 つの通知チャンネルがアクティブな場合でも、「オーバーラップ」期間が生じる可能性があることにご注意ください。

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

すべての通知メッセージには、X-Goog- という接頭辞を持つ一連の HTTP ヘッダーが含まれます。通知のタイプによっては、メッセージ本文を含めることもできます。

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

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"
        }
      ]
    }
  ]
}

お知らせに対応する

成功を示すには、200、201、202、204、または 102 のいずれかのステータス コードを返します。

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

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

このセクションでは、Admin SDK API でプッシュ通知を使用する際に受信できる通知メッセージについて詳しく説明します。

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

• admin
• カレンダー
• ドライブ
• グループ
• login
• モバイル
• saml
• token
• user_accounts