APN 토큰의 등록 토큰을 만듭니다. 이 API를 사용하면 기존 APN 토큰을 대량으로 가져와서 FCM의 유효한 등록 토큰에 매핑할 수 있습니다.
앱 인스턴스 정보 가져오기
앱 인스턴스에 관한 정보를 가져오려면 이 엔드포인트에서 Instance ID 서비스를 호출하면서 앱 인스턴스의 토큰을 다음과 같이 제공하면 됩니다.
https://iid.googleapis.com/iid/info/IID_TOKEN
매개변수
Authorization: Bearer <access_token>. 헤더에서 이 매개변수를 설정합니다.
단기 OAuth2 토큰을 Authorization 헤더의 값으로 추가합니다.
이 토큰을 획득하는 방법에 대한 자세한 내용은 수동으로 사용자 인증 정보 제공을 참고하세요.
access_token_auth: true. 헤더에서 이 매개변수를 설정합니다.
[선택사항] 불리언 details: 이 토큰과 연결된 FCM 주제 구독 정보 (있는 경우)를 가져오려면 이 쿼리 매개변수를 true로 설정합니다. 지정하지 않으면 기본값은 false입니다.
결과
호출이 성공하면 HTTP 상태 200과 다음이 포함된 JSON 객체가 반환됩니다.
application - 토큰과 연결된 패키지 이름입니다.
authorizedEntity - 토큰으로 전송할 권한이 부여된 프로젝트 ID입니다.
applicationVersion - 애플리케이션 버전입니다.
platform - 토큰이 속한 기기 플랫폼을 나타내는 ANDROID, IOS 또는 CHROME를 반환합니다.
Authorization: Bearer <access_token>. 헤더에서 이 매개변수를 설정합니다.
단기 OAuth2 토큰을 Authorization 헤더의 값으로 추가합니다.
이 토큰을 획득하는 방법에 대한 자세한 내용은 수동으로 사용자 인증 정보 제공을 참고하세요.
인스턴스 ID 서비스의 일괄 메서드를 사용하면 앱 인스턴스를 일괄 관리할 수 있습니다. 예를 들어 FCM 주제에 앱 인스턴스를 일괄적으로 추가하거나 삭제할 수 있습니다.
API 호출당 최대 1,000개의 앱 인스턴스를 업데이트하려면 이 엔드포인트에서 Instance ID 서비스를 호출하면서 JSON 본문에 앱 인스턴스 토큰을 제공하면 됩니다.
Authorization: Bearer <access_token>. 헤더에서 이 매개변수를 설정합니다.
단기 OAuth2 토큰을 Authorization 헤더의 값으로 추가합니다.
이 토큰을 획득하는 방법에 대한 자세한 내용은 수동으로 사용자 인증 정보 제공을 참고하세요.
HTTP 200 OK
{
"results":[
{},
{"error":"NOT_FOUND"},
{},
]
}
APNs 토큰의 등록 토큰 만들기
인스턴스 ID 서비스의 batchImport 메서드를 사용하면 기존 iOS APN 토큰을 Firebase 클라우드 메시징으로 대량 가져와 유효한 등록 토큰에 매핑할 수 있습니다. 이 엔드포인트에서 Instance ID 서비스를 호출하면서 JSON 본문에 APNs 토큰 목록을 제공하면 됩니다.
https://iid.googleapis.com/iid/v1:batchImport
응답 본문에는 해당 APN 기기 토큰에 FCM 메시지를 전송하는 데 사용할 수 있는 인스턴스 ID 등록 토큰 배열이 포함됩니다.
매개변수
Authorization: Bearer <access_token>. 헤더에서 이 매개변수를 설정합니다.
단기 OAuth2 토큰을 Authorization 헤더의 값으로 추가합니다.
이 토큰을 획득하는 방법에 대한 자세한 내용은 수동으로 사용자 인증 정보 제공을 참고하세요.
access_token_auth: true. 헤더에서 이 매개변수를 설정합니다.
application : 앱의 번들 ID입니다.
sandbox : 샌드박스 환경 (TRUE) 또는 프로덕션 (FALSE)을 나타내는 불리언
HTTP200OK{"results":[{"apns_token":"368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12","status":"OK","registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"},{"apns_token":"76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86","status":"Internal Server Error"},]}
오류 응답
인스턴스 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) - 서비스를 사용할 수 없습니다. 지수 백오프로 요청을 다시 시도합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThe Instance ID service allows server-side management of app instances, including retrieving information, creating relationship maps, and managing APNs tokens.\u003c/p\u003e\n"],["\u003cp\u003eYou can get information about an app instance, such as its package name, authorized project ID, application version, and platform, by calling the Instance ID service with the app instance's token.\u003c/p\u003e\n"],["\u003cp\u003eRelationship maps, like subscribing an app instance to an FCM topic, can be created and managed individually or in bulk using the Instance ID service.\u003c/p\u003e\n"],["\u003cp\u003eExisting iOS APNs tokens can be bulk imported to Firebase Cloud Messaging and mapped to valid registration tokens using the \u003ccode\u003ebatchImport\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eThe Instance ID server API returns standard HTTP error codes for issues like bad requests, unauthorized access, forbidden actions, not found resources, and service unavailability.\u003c/p\u003e\n"]]],[],null,["# Server Reference\n\nServer implementation is optional. Use the Instance ID service if you want\nto perform these operations:\n\n- [Get information about app instances](/instance-id/reference/server#get_information_about_app_instances). Verify app tokens or get more information about the app instance that created the token.\n- [Create relationship maps for app instances](/instance-id/reference/server#create_relationship_maps_for_app_instances). Create relationships between app instances and entities.\n- [Create registration tokens for APNs tokens](/instance-id/reference/server#create_registration_tokens_for_apns_tokens). This API lets you bulk import existing APNs tokens, mapping them to valid registration tokens for FCM.\n\nGet information about app instances\n-----------------------------------\n\nTo get information about an app instance, call the Instance ID service at\nthis endpoint, providing the app instance's token as shown: \n\n https://iid.googleapis.com/iid/info/IID_TOKEN\n\n### Parameters\n\n- `Authorization: Bearer \u003caccess_token\u003e`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).\n- `access_token_auth: true`. Set this parameter in the header.\n- \\[optional\\] boolean `details`: set this query parameter to `true` to get FCM topic subscription information (if any) associated with this token. When not specified, defaults to `false`.\n\n### Results\n\nOn success the call returns HTTP status 200 and a JSON object containing:\n\n- `application` - package name associated with the token.\n- `authorizedEntity` - projectId authorized to send to the token.\n- `applicationVersion` - version of the application.\n- `platform` - returns `ANDROID`, `IOS`, or `CHROME` to indicate the device platform to which the token belongs.\n\nIf the `details` flag is set:\n\n- `rel` - relations associated with the token. For example, a list of topic subscriptions.\n\n### Example `GET` request\n\n https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA\n Content-Type:application/json\n Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA\n access_token_auth: true\n\nExample result\n--------------\n\n HTTP 200 OK\n {\n \"application\":\"com.iid.example\",\n \"authorizedEntity\":\"123456782354\",\n \"platform\":\"Android\",\n \"rel\":{\n \"topics\":{\n \"topicname1\":{\"addDate\":\"2015-07-30\"},\n \"topicname2\":{\"addDate\":\"2015-07-30\"},\n \"topicname3\":{\"addDate\":\"2015-07-30\"},\n \"topicname4\":{\"addDate\":\"2015-07-30\"}\n }\n }\n }\n\nCreate relationship maps for app instances\n------------------------------------------\n\nThe Instance ID API lets you create relationship maps for app instances.\nFor example, you can map a registration token to an FCM topic,\nsubscribing the app instance to the topic. The API provides methods for creating\nsuch relationships both individually, and in bulk.\n\n### Create a relation mapping for an app instance\n\nGiven a registration token and a supported relationship, you can create\na mapping. For example, you can subscribe an app instance to an FCM topic\nby calling the Instance ID service at\nthis endpoint, providing the app instance's token as shown: \n\n https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME\n\n#### Parameters\n\n- `Authorization: Bearer \u003caccess_token\u003e`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).\n- `access_token_auth: true`. Set this parameter in the header.\n\n#### Results\n\nOn success the call returns HTTP status 200.\n\n#### Example `POST` request\n\n https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies\n Content-Type:application/json\n Content-Length: 0\n Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA\n access_token_auth: true\n\n#### Example result\n\n HTTP 200 OK\n {}\n\n### Manage relationship maps for multiple app instances\n\nUsing the Instance ID service's batch methods, you can perform batch\nmanagement of app instances. For example, you can perform bulk\naddition or removal of app instances to an FCM topic.\nTo update up to 1000 app instances per API call, call the Instance ID\nservice at this endpoint, providing the app instance tokens in the JSON body: \n\n https://iid.googleapis.com/iid/v1:batchAdd\n\n https://iid.googleapis.com/iid/v1:batchRemove\n\n#### Parameters\n\n- `Authorization: Bearer \u003caccess_token\u003e`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).\n- `access_token_auth: true`. Set this parameter in the header.\n- `to` : The topic name.\n- `registration_tokens` : The array of IID tokens for the app instances you want to add or remove.\n\n#### Results\n\nOn success the call returns HTTP status 200. Empty results indicate successful\nsubscription for the token. For failed subscriptions, the result contains one\nof these error codes:\n\n- NOT_FOUND --- The registration token has been deleted or the app has been uninstalled.\n- INVALID_ARGUMENT --- The registration token provided is not valid for the Sender ID.\n- INTERNAL --- The backend server failed for unknown reasons. Retry the request.\n- TOO_MANY_TOPICS --- Excessive number of topics per app instance.\n- RESOURCE_EXHAUSTED --- Too many subscription or unsubscription requests in a short period of time. Retry with exponential backoff.\n\n#### Example `POST` request\n\n https://iid.googleapis.com/iid/v1:batchAdd\n Content-Type:application/json\n Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA\n access_token_auth: true\n {\n \"to\": \"/topics/movies\",\n \"registration_tokens\": [\"nKctODamlM4:CKrh_PC8kIb7O...\", \"1uoasi24:9jsjwuw...\", \"798aywu:cba420...\"],\n }\n\n#### Example result\n\n HTTP 200 OK\n {\n \"results\":[\n {},\n {\"error\":\"NOT_FOUND\"},\n {},\n ]\n }\n\nCreate registration tokens for APNs tokens\n------------------------------------------\n\nUsing the Instance ID service's `batchImport` method, you can bulk import\nexisting iOS APNs tokens to Firebase Cloud Messaging, mapping them\nto valid registration tokens. Call the Instance ID service at\nthis endpoint, providing a list of APNs tokens in the JSON body: \n\n https://iid.googleapis.com/iid/v1:batchImport\n\nThe response body contains an array of Instance ID registration tokens ready\nto be used for sending FCM messages to the corresponding APNs device token.\n| **Note:** The list of APNs tokens in each request cannot exceed 100.\n\n### Parameters\n\n- `Authorization: Bearer \u003caccess_token\u003e`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).\n- `access_token_auth: true`. Set this parameter in the header.\n- `application` : Bundle id of the app.\n- `sandbox` : Boolean to indicate sandbox environment (TRUE) or production (FALSE)\n- `apns_tokens` : The array of APNs tokens for the app instances you want to add or remove. Maximum 100 tokens per request.\n\n### Results\n\nOn success the call returns HTTP status 200 and a JSON result body. For each\nAPNs token provided in the request, the results list includes:\n\n- The APNs token.\n- Status. Either OK, or an error message describing the failure.\n- For successful results, the registration token that FCM maps to the APNs token.\n\n### Example `POST` request\n\n https://iid.googleapis.com/iid/v1:batchImport\n Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA\n access_token_auth:true\n {\n \"application\": \"com.google.FCMTestApp\",\n \"sandbox\":false,\n \"apns_tokens\":[\n \"368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12\",\n \"76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86\"\n ]\n }\n\n### Example result\n\n HTTP 200 OK\n {\n \"results\":[\n {\n \"apns_token\": \"368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12\",\n \"status\": \"OK\",\n \"registration_token\":\"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA\"\n },\n {\n \"apns_token\": \"76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86\",\n \"status\":\"Internal Server Error\"\n },\n ]\n }\n\nError responses\n---------------\n\nCalls to the Instance ID server API return\nthe following HTTP error codes:\n\n- `HTTP status 400 (Bad request)` - request parameters are missing or invalid. Check error messages for detailed information.\n- `HTTP status 401 (Unauthorized)` - authorization header is invalid.\n- `HTTP status 403 (Forbidden)` - authorization header doesn't match the `authorizedEntity`.\n- `HTTP status 404 (Not found)` - Invalid HTTP path or IID token not found. Check error messages for detailed information.\n- `HTTP status 503 (Service unavailable)` - service is unavailable. Retry the request with exponential backoff."]]
