サーバーの実装は任意です。次の操作を行う場合は、インスタンス ID サービスを使用します。
- アプリ インスタンスに関する情報を取得する。アプリ トークンを検証するか、トークンを作成したアプリ インスタンスに関する詳細情報を取得します。
- アプリ インスタンスのリレーション マップを作成する。アプリ インスタンスとエンティティの間にリレーションを作成します。
- APNs トークンの登録トークンを作成する。この API を使用すると、既存の APNs トークンを一括でインポートして、FCM の有効な登録トークンにマッピングできます。
アプリ インスタンスに関する情報を取得する
アプリ インスタンスに関する情報を取得するには、次に示すようにアプリ インスタンスのトークンを指定して、このエンドポイントでインスタンス ID サービスを呼び出します。
https://iid.googleapis.com/iid/info/IID_TOKEN
パラメータ
Authorization: Bearer <access_token>
。このパラメータはヘッダーに設定します。有効期間の短い OAuth2 トークンをAuthorization
ヘッダーの値として追加します。このトークンの取得の詳細については、認証情報を手動で提供するをご覧ください。access_token_auth: true
。このパラメータはヘッダーに設定します。- (省略可)ブール値
details
: このクエリ パラメータをtrue
に設定すると、このトークンに関連付けられた FCM トピック サブスクリプション情報(存在する場合)を取得します。指定しない場合のデフォルトはfalse
です。
結果
成功すると、この呼び出しは HTTP ステータス 200 と、以下を含む JSON オブジェクトを返します。
application
- トークンに関連付けられているパッケージ名。authorizedEntity
- トークンへの送信が承認されたプロジェクト ID。applicationVersion
- アプリケーションのバージョン。platform
- トークンが属するデバイス プラットフォームを示すANDROID
、IOS
、またはCHROME
を返します。
details
フラグが設定されている場合:
rel
- トークンに関連付けられているリレーション。たとえば、トピック サブスクリプションのリストです。
GET
リクエストの例
https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
結果の例
HTTP 200 OK
{
"application":"com.iid.example",
"authorizedEntity":"123456782354",
"platform":"Android",
"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 を使用すると、アプリ インスタンスのリレーション マップを作成できます。たとえば、登録トークンを FCM トピックにマッピングして、アプリ インスタンスをトピックにサブスクライブできます。この API には、このような関係を個別または一括で作成するメソッドが用意されています。
アプリ インスタンスのリレーション マッピングを作成する
登録トークンとサポートされている関係がある場合、マッピングを作成できます。たとえば、次に示すようにアプリ インスタンスのトークンを指定して、このエンドポイントでインスタンス ID サービスを呼び出し、アプリ インスタンスを FCM トピックにサブスクライブできます。
https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME
パラメータ
Authorization: Bearer <access_token>
。このパラメータはヘッダーに設定します。有効期間の短い OAuth2 トークンをAuthorization
ヘッダーの値として追加します。このトークンの取得の詳細については、認証情報を手動で提供するをご覧ください。access_token_auth: true
。このパラメータはヘッダーに設定します。
結果
成功すると、HTTP ステータス 200 が返されます。
POST
リクエストの例
https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
結果の例
HTTP 200 OK
{}
複数のアプリ インスタンスのリレーション マップを管理する
インスタンス ID サービスのバッチメソッドを使用すると、アプリ インスタンスのバッチ管理を実行できます。たとえば、FCM トピックへのアプリ インスタンスの追加や削除を一括で行うことができます。API 呼び出しごとに最大 1,000 個のアプリ インスタンスを更新するには、このエンドポイントでインスタンス ID サービスを呼び出し、JSON 本文でアプリ インスタンス トークンを指定します。
https://iid.googleapis.com/iid/v1:batchAdd
https://iid.googleapis.com/iid/v1:batchRemove
パラメータ
Authorization: Bearer <access_token>
。このパラメータはヘッダーに設定します。有効期間の短い OAuth2 トークンをAuthorization
ヘッダーの値として追加します。このトークンの取得の詳細については、認証情報を手動で提供するをご覧ください。access_token_auth: true
。このパラメータはヘッダーに設定します。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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
"to": "/topics/movies",
"registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}
結果の例
HTTP 200 OK
{
"results":[
{},
{"error":"NOT_FOUND"},
{},
]
}
APNs トークンの登録トークンを作成する
インスタンス ID サービスの batchImport
メソッドを使用して、既存の iOS APNs トークンを Firebase Cloud Messaging に一括インポートし、有効な登録トークンにマッピングできます。このエンドポイントでインスタンス ID サービスを呼び出し、JSON 本文で APNs トークンのリストを指定します。
https://iid.googleapis.com/iid/v1:batchImport
レスポンスの本文には、対応する APNs デバイス トークンへの FCM メッセージの送信に使用できるインスタンス ID 登録トークンの配列が含まれます。
パラメータ
Authorization: Bearer <access_token>
。このパラメータはヘッダーに設定します。有効期間の短い OAuth2 トークンをAuthorization
ヘッダーの値として追加します。このトークンの取得の詳細については、認証情報を手動で提供するをご覧ください。access_token_auth: true
。このパラメータはヘッダーに設定します。application
: アプリのバンドル ID。sandbox
: サンドボックス環境(TRUE)または本番環境(FALSE)を示すブール値apns_tokens
: 追加または削除するアプリ インスタンスの APNs トークンの配列。リクエストごとのトークンの最大数は 100 です。
結果
成功すると、呼び出しは HTTP ステータス 200 と JSON 結果本文を返します。リクエストで指定された APNs トークンごとに、結果リストには次のものが含まれます。
- APNs トークン。
- ステータス。OK、または失敗を説明するエラー メッセージ。
- 成功した場合、FCM が APNs トークンにマッピングする登録トークン。
POST
リクエストの例
https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
"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"
},
]
}
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)
- サービスは利用できません。指数バックオフでリクエストを再試行します。