サーバー リファレンス

サーバーの実装は任意です。次の操作を行う場合は、インスタンス ID サービスを使用します。

アプリ インスタンスに関する情報を取得する

アプリ インスタンスに関する情報を取得するには、このエンドポイントでインスタンス ID サービスを呼び出して、アプリ インスタンスのトークンを次のように指定します。

 https://iid.googleapis.com/iid/info/IID_TOKEN

パラメータ

  • Authorization: key=YOUR_API_KEY。ヘッダーでこのパラメータを設定します。
  • [省略可] ブール値 details: このクエリ パラメータを true に設定して、このトークンに関連付けられた FCM または GCM トピックのサブスクリプション情報(存在する場合)を取得します。指定しない場合のデフォルトは false です。

結果

成功すると、呼び出しは HTTP ステータス 200 と以下を含む JSON オブジェクトを返します。

  • application - トークンに関連付けられたパッケージ名。
  • authorizedEntity - トークンの送信が許可されている projectId。
  • applicationVersion - アプリケーションのバージョン。
  • appSigner - パッケージに適用される署名の sha1 フィンガープリント。アプリに署名した当事者を示します(例: Play Store)。
  • platform - トークンが属するデバイス プラットフォームを示す ANDROIDIOS、または CHROME を返します。

details フラグが設定されている場合:

  • rel - トークンに関連付けられたリレーション。(トピックのサブスクリプションのリストなど)。

GET リクエストの例

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

結果の例

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "appSigner":"1a2bc3d4e5"
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

アプリ インスタンス用のリレーション マップの作成

Instance ID API を使用すると、アプリ インスタンスの関係マップを作成できます。たとえば、登録トークンを Google Cloud Messaging トピックにマッピングして、アプリ インスタンスをトピックにサブスクライブできます。API には、このような関係を個別または一括で作成するためのメソッドが用意されています。

アプリ インスタンスのリレーション マッピングを作成する

登録トークンとサポートされている関係を指定して、マッピングを作成できます。たとえば、次に示すように、このエンドポイントでインスタンス ID サービスを呼び出して、アプリ インスタンスを Google Cloud Messaging トピックにサブスクライブできます。

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

パラメータ

  • Authorization: key=YOUR_API_KEY。ヘッダーでこのパラメータを設定します。

結果

成功すると、呼び出しは HTTP ステータス 200 を返します。

POST リクエストの例

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

結果の例

HTTP 200 OK
{}

複数のアプリ インスタンスのリレーション マップを管理する

インスタンス ID サービスのバッチメソッドを使用すると、アプリ インスタンスのバッチ管理を実行できます。たとえば、アプリ インスタンスを FCM または GCM トピックに一括追加または削除できます。API 呼び出しごとに最大 1,000 個のアプリ インスタンスを更新するには、このエンドポイントでインスタンス ID サービスを呼び出し、JSON 本文でアプリ インスタンス トークンを指定します。

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

パラメータ

  • Authorization: key=YOUR_API_KEY。ヘッダーでこのパラメータを設定します。
  • to : トピック名。
  • registration_tokens : 追加または削除するアプリ インスタンスの IID トークンの配列。

結果

成功すると、呼び出しは HTTP ステータス 200 を返します。空の結果は、トークンの登録が成功したことを示します。失敗したサブスクリプションの場合、結果には次のいずれかのエラーコードが含まれます。

  • NOT_FOUND - 登録トークンが削除されたか、アプリがアンインストールされました。
  • INVALID_ARGUMENT - 提供された登録トークンが送信者 ID に対して無効です。
  • INTERNAL - バックエンド サーバーは不明な理由で失敗しました。リクエストを再試行します。
  • TOO_MANY_TOPICS - アプリ インスタンスあたりのトピック数が多すぎる。
  • RESOURCE_EXHAUSTED - 短期間にサブスクリプションまたは登録解除リクエストが多すぎます。指数バックオフで再試行します。

POST リクエストの例

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

結果の例

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

APNs トークンの登録トークンを作成する

インスタンス ID サービスの batchImport メソッドを使用して、既存の iOS APNs トークンを Google Cloud Messaging または Firebase Cloud Messaging に一括インポートし、有効な登録トークンにマッピングできます。このエンドポイントでインスタンス ID サービスを呼び出し、JSON 本文で APNs トークンのリストを指定します。

 https://iid.googleapis.com/iid/v1:batchImport

レスポンスの本文には、対応する APNs デバイス トークンに FCM または GCM メッセージを送信する際に使用できるインスタンス ID 登録トークンの配列が含まれます。

パラメータ

  • Authorization: key=YOUR_API_KEY。ヘッダーでこのパラメータを設定します。
  • application : アプリのバンドル ID。
  • sandbox : サンドボックス環境(TRUE)または本番環境(FALSE)を示すブール値
  • apns_tokens : 追加または削除するアプリ インスタンスの APNs トークンの配列。リクエストごとに最大 100 個のトークン。

結果

成功すると、呼び出しは HTTP ステータス 200 と JSON 結果本文を返します。結果リストには、リクエストで指定された各 APNs トークンが含まれます。

  • APNs トークン。
  • ステータス。[OK] またはエラーを説明するエラー メッセージ。
  • 成功するには、FCM または GCM が APNs トークンにマッピングされる登録トークン。

POST リクエストの例

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

結果の例

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

push サブスクリプションの登録トークンの管理

インスタンス ID サービスのウェブメソッドを使用すると、Firebase Cloud Messaging の既存の push サブスクリプションをインポートできます。更新と削除も可能です。

push サブスクリプションをインポートすると、登録トークンが届きます。このトークンを使用すると、トピック メッセージングやデバイス グループ メッセージングなどの FCM 機能を使用して、ウェブアプリの通知をターゲットにできます。

push サブスクリプションのインポート

InstanceID のウェブ エンドポイントを使用して push サブスクリプションをインポートできます。

 https://iid.googleapis.com/v1/web/iid

リクエストには、OAuth 2.0 アクセス トークンに設定された Authorization ヘッダー、アプリケーション サーバーキーに設定された暗号鍵ヘッダー、リクエスト本文の PushSubscription オブジェクトを含める必要があります。

レスポンスの本文には、ペイロードを暗号化せずに、対応するウェブアプリ インスタンスに FCM または GCM メッセージを送信するためにすぐに使用できる登録トークンが含まれています。

VAPID 鍵ペアをコンソールにアップロードします

鍵をインポートするには、Firebase プロジェクトに対するオーナーレベルのアクセス権が必要です。既存の公開鍵と秘密鍵を URL セーフの Base64 エンコード形式でインポートします。

  1. Firebase コンソールの [設定] ペインで [ Cloud Messaging] タブを開き、[ウェブ設定] セクションまでスクロールします。
  2. [ウェブプッシュ証明書] タブで、リンクテキスト「既存の鍵ペアをインポート」を見つけて選択します。
  3. [鍵ペアのインポート] ダイアログで公開鍵と秘密鍵をそれぞれのフィールドに入力し、[インポート] をクリックします。追加した公開鍵の文字列と日付がコンソールに表示されます。

OAuth2 トークンを取得する: 認証情報を使用してアクセス トークンを作成する

リクエストのアクセス トークンを作成するには、アクセス トークンを作成して HTTP リクエストに追加する必要があります。

node.js

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}

FCM へのアクセスを承認するには、スコープ https://www.googleapis.com/auth/firebase.messaging をリクエストします。

パラメータ

  • 承認: Bearer <access_token>。ヘッダーでこのパラメータを設定します。
  • 暗号鍵: p256ecdsa=APPLICATION_PUBLIC_KEY。ヘッダーでこのパラメータを設定します。
  • リクエスト本文: PushSubscription.toJson()。push サブスクリプションを解析せずに HTTP 本文に渡します。コンテンツが PushSubscription の W3C エンコードと一致しています。

レスポンス

成功すると、呼び出しは HTTP ステータス 200 OK と IID トークンを含む JSON 結果本文を返します。

POST リクエストの例

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

結果の例

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

push サブスクリプションの更新

次のトークンを使用して、登録トークンに関連付けられた push サブスクリプションを更新できます。

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

パラメータ

  • 承認: Bearer <access_token>。ヘッダーでこのパラメータを設定します。
  • 暗号鍵: p256ecdsa=APPLICATION_PUBLIC_KEY。ヘッダーでこのパラメータを設定します。
  • リクエスト本文: PushSubscription.toJson()。push サブスクリプションを解析せずに HTTP 本文に渡します。コンテンツが PushSubscription の W3C エンコードと一致しています。

結果

成功すると、呼び出しは HTTP ステータス 200 と登録トークンを返します。これは、リクエストで渡したトークンと同じものにすることも、新しいトークンにすることもできます。

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

POST リクエストの例

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

結果の例

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

push サブスクリプションの削除

DELETE リクエストは、push サブスクリプションの詳細を FCM データベースから削除します。Push API プロトコルを使用すると、引き続きウェブ アプリケーションでメッセージを受信できます。

push サブスクリプションを削除するには、次の宛先に DELETE リクエストを送信します。

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

DELETE リクエストの例

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

結果の例

 HTTP 200 OK {}

Error responses(エラー応答)

インスタンス ID サーバー API を呼び出すと、次の HTTP エラーコードが返されます。

  • HTTP status 400 (Bad request) - リクエスト パラメータがないか、無効です。詳しくは、エラー メッセージをご覧ください。
  • HTTP status 401 (Unauthorized) - 認証ヘッダーが無効です。
  • HTTP status 403 (Forbidden) - 承認ヘッダーが authorizedEntity と一致しません。
  • HTTP status 404 (Not found) - 無効な HTTP パスまたは IID トークンが見つかりません。詳しくは、エラー メッセージをご覧ください。
  • HTTP status 503 (Service unavailable) - サービスを利用できません。この場合は、指数バックオフを使用してリクエストを再試行します。