サーバーの実装は省略可能です。これらの操作を行う場合は、インスタンス ID サービスを使用します。
- アプリ インスタンスに関する情報を取得する。アプリトークンを確認するか、トークンを作成したアプリ インスタンスに関する詳細情報を取得します。
- アプリ インスタンスのリレーション マップを作成する。アプリ インスタンスとエンティティ(FCM トピックや GCM トピックなど)の間に関係を作成します。
- APNs トークンの登録トークンを作成します。この API を使用すると、既存の APNs トークンを一括でインポートして、FCM または GCM の有効な登録トークンにマッピングできます。
- push サブスクリプションの登録トークンの管理。Push API を使用して実装されたウェブ アプリケーションの場合は、既存の push サブスクリプションをインポートし、FCM の有効な登録トークンにマッピングします。
アプリ インスタンスに関する情報を取得する
アプリ インスタンスに関する情報を取得するには、このエンドポイントでインスタンス 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 は、このようなリレーションを個別にまたは一括で作成するメソッドを提供します。
アプリ インスタンスのリレーション マッピングを作成する
登録トークンとサポートされている関係を指定することで、マッピングを作成できます。たとえば、次に示すように、このエンドポイントでインスタンス 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 エンコード形式でインポートします。
- Firebase コンソールの [設定] ペインで [Cloud Messaging] タブを開き、[ウェブ設定] セクションまでスクロールします。
- [ウェブプッシュ証明書] タブで、リンクテキスト「既存の鍵ペアをインポート」を見つけて選択します。
- [鍵ペアのインポート] ダイアログで公開鍵と秘密鍵をそれぞれのフィールドに入力し、[インポート] をクリックします。追加した公開鍵の文字列と日付がコンソールに表示されます。
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)
- サービスを利用できません。指数バックオフを使用してリクエストを再試行します。