Tham chiếu máy chủ

Việc triển khai máy chủ là không bắt buộc. Sử dụng dịch vụ mã phiên bản nếu bạn muốn để thực hiện các thao tác này:

Xem thông tin về các phiên bản ứng dụng

Để biết thông tin về một phiên bản ứng dụng, hãy gọi dịch vụ mã phiên bản tại điểm cuối này, cung cấp mã thông báo của phiên bản ứng dụng như sau:

 https://iid.googleapis.com/iid/info/IID_TOKEN

Tham số

  • Authorization: Bearer <access_token>. Hãy đặt thông số này trong tiêu đề. Thêm mã thông báo OAuth2 ngắn hạn làm giá trị của tiêu đề Authorization. Để biết thêm thông tin về cách nhận mã thông báo này, hãy xem Cung cấp thông tin đăng nhập theo cách thủ công.
  • access_token_auth: true. Hãy đặt thông số này trong tiêu đề.
  • [không bắt buộc] boolean details: đặt tham số truy vấn này thành true để nhận FCM thông tin đăng ký chủ đề (nếu có) được liên kết với mã thông báo này. Khi không đã chỉ định, giá trị mặc định là false.

Kết quả

Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 và đối tượng JSON chứa:

  • application – tên gói liên kết với mã thông báo.
  • authorizedEntity – projectId được phép gửi tới mã thông báo.
  • applicationVersion - phiên bản của ứng dụng.
  • platform – trả về ANDROID, IOS hoặc CHROME để cho biết thiết bị nền tảng chứa mã thông báo.

Nếu bạn đặt cờ details:

  • rel – các quan hệ liên kết với mã thông báo. Ví dụ: danh sách chủ đề gói thuê bao.

Ví dụ về yêu cầu 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

Ví dụ về kết quả

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"}
    }
  }
}

Tạo bản đồ mối quan hệ cho các thực thể ứng dụng

Instance ID API cho phép bạn tạo bản đồ mối quan hệ cho các thực thể ứng dụng. Ví dụ: bạn có thể liên kết một mã thông báo đăng ký với một chủ đề FCM, đăng ký phiên bản ứng dụng với chủ đề. API này cung cấp các phương thức để tạo các mối quan hệ như vậy, cả về phương diện riêng lẻ và hàng loạt.

Tạo bản đồ ánh xạ mối quan hệ cho một thực thể ứng dụng

Khi được cung cấp mã thông báo đăng ký và mối quan hệ được hỗ trợ, bạn có thể tạo ánh xạ. Ví dụ: bạn có thể đăng ký một phiên bản ứng dụng theo chủ đề FCM bằng cách gọi dịch vụ Mã thực thể tại điểm cuối này, cung cấp mã thông báo của phiên bản ứng dụng như sau:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Tham số

  • Authorization: Bearer <access_token>. Hãy đặt thông số này trong tiêu đề. Thêm mã thông báo OAuth2 ngắn hạn làm giá trị của tiêu đề Authorization. Để biết thêm thông tin về cách nhận mã thông báo này, hãy xem Cung cấp thông tin đăng nhập theo cách thủ công.
  • access_token_auth: true. Hãy đặt thông số này trong tiêu đề.

Kết quả

Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200.

Ví dụ về yêu cầu 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

Ví dụ về kết quả

HTTP 200 OK
{}

Quản lý bản đồ mối quan hệ cho nhiều thực thể ứng dụng

Khi sử dụng các phương thức theo lô của dịch vụ mã thực thể, bạn có thể thực hiện hàng loạt quản lý các phiên bản ứng dụng. Ví dụ: bạn có thể thực hiện hàng loạt thêm hoặc xoá các phiên bản ứng dụng khỏi một chủ đề FCM. Để cập nhật lên đến 1.000 phiên bản ứng dụng cho mỗi lệnh gọi API, hãy gọi mã phiên bản dịch vụ tại điểm cuối này, cung cấp mã thông báo thực thể ứng dụng trong phần nội dung JSON:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

Tham số

  • Authorization: Bearer <access_token>. Hãy đặt thông số này trong tiêu đề. Thêm mã thông báo OAuth2 ngắn hạn làm giá trị của tiêu đề Authorization. Để biết thêm thông tin về cách nhận mã thông báo này, hãy xem Cung cấp thông tin đăng nhập theo cách thủ công.
  • access_token_auth: true. Hãy đặt thông số này trong tiêu đề.
  • to : Tên chủ đề.
  • registration_tokens : Mảng mã thông báo IID cho các phiên bản ứng dụng mà bạn muốn thêm hoặc xoá.

Kết quả

Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200. Kết quả trống cho biết thành công cho mã thông báo. Đối với các gói thuê bao không thành công, kết quả chứa một trong số các mã lỗi sau:

  • NOT_FOUND — Mã thông báo đăng ký đã bị xoá hoặc ứng dụng đã bị gỡ cài đặt.
  • INVALID_ARGUMENT — Mã thông báo đăng ký được cung cấp không hợp lệ cho ID người gửi.
  • NỘI BỘ — Máy chủ phụ trợ bị lỗi vì lý do không xác định. Thử gửi lại yêu cầu.
  • TOO_MANY_TOPICS — Có quá nhiều chủ đề cho mỗi phiên bản ứng dụng.
  • resource_EXHAUSTED — Quá nhiều yêu cầu đăng ký hoặc hủy đăng ký trong một khoảng thời gian ngắn. Thử lại với thời gian đợi luỹ thừa.

Ví dụ về yêu cầu 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..."],
}

Ví dụ về kết quả

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Tạo mã đăng ký cho mã thông báo APN

Khi sử dụng phương thức batchImport của dịch vụ mã thực thể, bạn có thể nhập hàng loạt mã thông báo APN hiện có của iOS với Giải pháp gửi thông báo qua đám mây của Firebase, ánh xạ các mã đó vào mã thông báo đăng ký hợp lệ. Gọi dịch vụ mã phiên bản theo số điểm cuối này, cung cấp danh sách mã thông báo APN trong phần nội dung JSON:

 https://iid.googleapis.com/iid/v1:batchImport

Nội dung phản hồi chứa một loạt mã thông báo đăng ký mã thực thể đã sẵn sàng được dùng để gửi thông báo FCM đến mã thông báo thiết bị APN tương ứng.

Tham số

  • Authorization: Bearer <access_token>. Hãy đặt thông số này trong tiêu đề. Thêm mã thông báo OAuth2 ngắn hạn làm giá trị của tiêu đề Authorization. Để biết thêm thông tin về cách nhận mã thông báo này, hãy xem Cung cấp thông tin đăng nhập theo cách thủ công.
  • access_token_auth: true. Hãy đặt thông số này trong tiêu đề.
  • application : Mã gói của ứng dụng.
  • sandbox : Giá trị boolean cho biết môi trường hộp cát (TRUE) hoặc sản xuất (FALSE)
  • apns_tokens : Mảng mã thông báo APN cho các thực thể ứng dụng bạn muốn thêm hoặc xoá. Tối đa 100 mã thông báo cho mỗi yêu cầu.

Kết quả

Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 và nội dung kết quả JSON. Đối với mỗi Mã thông báo APN được cung cấp trong yêu cầu, danh sách kết quả bao gồm:

  • Mã thông báo APN.
  • Trạng thái. OK hoặc một thông báo lỗi mô tả lỗi.
  • Để có kết quả thành công, mã thông báo đăng ký mà FCM liên kết với mã thông báo APN.

Ví dụ về yêu cầu 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"
   ]
}

Ví dụ về kết quả

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Phản hồi lỗi

Lệnh gọi đến dữ liệu trả về của Instance ID server API các mã lỗi HTTP sau đây:

  • HTTP status 400 (Bad request) – thông số yêu cầu bị thiếu hoặc không hợp lệ. Hãy kiểm tra thông báo lỗi để biết thông tin chi tiết.
  • HTTP status 401 (Unauthorized) – tiêu đề uỷ quyền không hợp lệ.
  • HTTP status 403 (Forbidden) - tiêu đề uỷ quyền không khớp với authorizedEntity
  • HTTP status 404 (Not found) – Không tìm thấy đường dẫn HTTP hoặc mã thông báo IID không hợp lệ. Hãy kiểm tra thông báo lỗi để biết thông tin chi tiết.
  • HTTP status 503 (Service unavailable) – dịch vụ không hoạt động. Thử lại có thời gian đợi luỹ thừa.