サーバー リファレンス

サーバーの実装は任意です。これらのオペレーションを実行する場合は、インスタンス 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 - ANDROID、IOS、または 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 には、このような関係を個別に、または一括で作成するためのメソッドが用意されています。

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

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

 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 回あたり最大 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 - アプリ インスタンスあたりのトピック数が多すぎる。

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

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

パラメータ

  • Authorization: key=YOUR_API_KEY。ヘッダーにこのパラメータを設定します。
  • application : アプリのバンドル ID。
  • sandbox: サンドボックス環境（TRUE）または本番環境（FALSE）を示すブール値
  • apns_tokens : 追加または削除するアプリ インスタンスの APNs トークンの配列。1 回のリクエストにつき最大 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 アクセス トークンに設定された承認ヘッダー、アプリケーション サーバーキーに設定された暗号鍵ヘッダー、リクエスト本文の 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);
      });
}
index.js

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
configure.py

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();
}
Configure.java

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 リクエストにより、FCM データベースから push サブスクリプションの詳細が削除されます。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) - サービスを利用できない。この場合は、指数バックオフを使用してリクエストを再試行します。