サーバー リファレンス

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

サーバーの実装は省略可能です。これらの操作を行う場合は、インスタンス 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 - トークンが属するデバイス プラットフォームを示す ANDROIDIOSCHROME を返します。

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

レスポンスの本文には、FCM や GCM のメッセージを対応する APNs デバイス トークンに送信するために使用できる、インスタンス 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 アクセス トークンに設定された認証トークン、アプリケーション サーバーキーに設定された暗号鍵ヘッダー、リクエスト本文の 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 サブスクリプションを更新する

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

 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) - サービスを利用できません。指数バックオフを使用してリクエストを再試行します。