Tham chiếu máy chủ

Stay organized with collections Save and categorize content based on your preferences.

Bạn không bắt buộc phải triển khai máy chủ. Hãy sử dụng dịch vụ Mã nhận dạng thực thể nếu bạn muốn thực hiện các thao tác này:

Nhận thông tin về các bản sao ứng dụng

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

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

Các tham số

  • Authorization: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.
  • [không bắt buộc] boolean details: đặt thông số truy vấn này thành true để nhận thông tin đăng ký chủ đề FCM hoặc GCM (nếu có) được liên kết với mã thông báo này. Khi không được chỉ định, giá trị mặc định sẽ 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 ủy quyền gửi đến mã thông báo.
  • applicationVersion – phiên bản của ứng dụng.
  • appSigner – vân tay sha1 cho chữ ký được áp dụng cho gói. Cho biết bên nào đã ký ứng dụng; ví dụ: Play Store.
  • platform – trả về ANDROID, IOS hoặc CHROME để cho biết nền tảng thiết bị chứa mã thông báo.

Nếu cờ details được đặt:

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

Ví dụ về yêu cầu GET

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Kết quả mẫu

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

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

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

Tạo mối liên kết mối quan hệ cho một phiên bản ứng dụng

Do có mã thông báo đăng ký và một mối quan hệ được hỗ trợ, bạn có thể tạo một liên kết. Ví dụ: bạn có thể đăng ký một phiên bản ứng dụng vào một chủ đề Nhắn tin qua đám mây của Google bằng cách gọi dịch vụ ID 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/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Các tham số

  • Authorization: key=YOUR_API_KEY. Đặ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:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Kết quả mẫu

HTTP 200 OK
{}

Quản lý bản đồ mối quan hệ cho nhiều phiên bản ứng dụng

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

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

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

Các tham số

  • Authorization: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.
  • to : Tên chủ đề.
  • registration_tokens : Dãy mã thông báo IID cho những 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 mã thông báo đăng ký thành công. Đối với các gói thuê bao không thành công, kết quả chứa một trong các mã lỗi sau:

  • NOT_FOUND — Mã thông báo đăng ký đã bị xóa hoặc ứng dụng đã bị gỡ cài đặt.
  • INVALID_ISBN — Mã thông báo đăng ký đã cung cấp không hợp lệ đối với ID người gửi.
  • NỘI BỘ — Máy chủ phụ trợ không thành công vì lý do không xác định. Thử gửi lại yêu cầu.
  • TOO_MANY_TOPIC — 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 huỷ đă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:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

Kết quả mẫu

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

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

Bằng cách sử dụng phương thức batchImport của dịch vụ Mã phiên bản, bạn có thể nhập hàng loạt mã thông báo APN iOS hiện có vào dịch vụ Nhắn tin qua đám mây của Google hoặc Giải pháp gửi thông báo qua đám mây của Firebase, liên kết các mã đó với mã thông báo đăng ký hợp lệ. Gọi dịch vụ Mã nhận dạng thực thể tại đ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

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

Các tham số

  • Authorization: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.
  • application : Mã nhận dạng gói của ứng dụng.
  • sandbox : Boolean để chỉ môi trường hộp cát (TRUE) hoặc sản xuất (FALSE)
  • apns_tokens : Dãy mã thông báo APN cho các phiên bản ứng dụng mà bạn muốn thêm hoặc xoá. Tối đa 100 mã thông báo 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ả sẽ bao gồm:

  • Mã thông báo APN.
  • Trạng thái. OK hoặc 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 hoặc GCM 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
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

Kết quả mẫu

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

Quản lý mã thông báo đăng ký cho các gói thuê bao đẩy

Bằng cách sử dụng các phương thức Web của dịch vụ ID phiên bản, bạn có thể nhập các gói thuê bao đẩy hiện có cho Giải pháp gửi thông báo qua đám mây của Firebase. Bạn cũng có thể cập nhật và xoá các ứng dụng đó.

Khi nhập một gói thuê bao đẩy, bạn sẽ nhận được mã thông báo đăng ký. Mã thông báo này cho phép bạn sử dụng các tính năng FCM như nhắn tin theo chủ đề và nhắn tin nhóm thiết bị để nhắm mục tiêu thông báo đến các ứng dụng web của bạn.

Nhập gói thuê bao đẩy

Bạn có thể nhập các gói thuê bao đẩy bằng điểm cuối web của InstanceID:

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

Yêu cầu phải chứa tiêu đề ủy quyền được đặt thành mã truy cập OAuth 2.0, tiêu đề khoá mã hoá được đặt thành khoá máy chủ ứng dụng và đối tượng PushSubscription trong nội dung yêu cầu.

Nội dung phản hồi chứa mã thông báo đăng ký sẵn sàng dùng để gửi thông báo FCM hoặc GCM tới phiên bản ứng dụng web tương ứng mà không phải mã hóa trọng tải.

Tải cặp khoá VAPID lên bảng điều khiển

Để nhập khoá, bạn phải có quyền truy cập ở cấp độ chủ sở hữu vào dự án Firebase. Nhập khoá công khai và riêng tư hiện có của bạn ở biểu mẫu mã hoá an toàn cho URL 64:

  1. Mở thẻ Gửi thông báo qua đám mây của ngăn Cài đặt của Bảng điều khiển của Firebase rồi cuộn đến phần Cấu hình web.
  2. Trong thẻ Chứng chỉ Web Push, hãy tìm và chọn văn bản liên kết, "nhập một cặp khoá hiện có".
  3. Trong hộp thoại Nhập cặp khóa, cung cấp khóa công khai và riêng tư của bạn vào các trường tương ứng và nhấp vào Nhập. Bảng điều khiển hiển thị ngày và chuỗi khoá công khai đã thêm.

Truy xuất mã thông báo OAuth2: Sử dụng thông tin xác thực để tạo mã truy cập mint

Để tạo mã truy cập cho yêu cầu này, bạn cần phải tạo mã truy cập và thêm mã đó vào yêu cầu HTTP.

nút.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);
      });
}
index.js

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
configure.py

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();
}
Configure.java

Để cho phép truy cập vào FCM, hãy yêu cầu phạm vi https://www.googleapis.com/auth/firebase.messaging.

Các tham số

  • Uỷ quyền: Bearer <access_token>. Đặt thông số này trong tiêu đề.
  • Khoá mã hoá: p256ecdsa=APPLICATION_PUBLIC_KEY. Đặt thông số này trong tiêu đề.
  • Nội dung yêu cầu: PushSubscription.toJson(). Chuyển gói thuê bao đẩy đến nội dung HTTP mà không cần phân tích cú pháp. Nội dung khớp với mã hoá W3C của PushSubscription.

Phản hồi

Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 OK và nội dung kết quả JSON chứa mã thông báo IID.

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

Kết quả mẫu

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Cập nhật gói thuê bao đẩy

Bạn có thể cập nhật gói thuê bao đẩy được liên kết với mã thông báo đăng ký của mình bằng cách sử dụng điểm cuối sau:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

Các tham số

  • Uỷ quyền: Bearer <access_token>. Đặt thông số này trong tiêu đề.
  • Khoá mã hoá: p256ecdsa=APPLICATION_PUBLIC_KEY. Đặt thông số này trong tiêu đề.
  • Nội dung yêu cầu: PushSubscription.toJson(). Chuyển gói thuê bao đẩy đến nội dung HTTP mà không cần phân tích cú pháp. Nội dung khớp với mã hoá W3C của PushSubscription.

Kết quả

Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 và mã thông báo đăng ký. Đây có thể là mã mà bạn đã chuyển trong yêu cầu hoặc là mã thông báo mới.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

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

Kết quả mẫu

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

Xoá gói thuê bao đẩy

Yêu cầu DELETE xoá thông tin đăng ký đẩy khỏi cơ sở dữ liệu FCM. Bạn vẫn có thể nhận thông báo trong ứng dụng web của mình bằng cách sử dụng giao thức Push API.

Để xoá gói thuê bao đẩy, hãy gửi yêu cầu DELETE đến:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

Ví dụ về yêu cầu DELETE

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Kết quả mẫu

 HTTP 200 OK {}

Phản hồi lỗi

Các lệnh gọi đến API máy chủ mã nhận dạng sẽ trả về các mã lỗi HTTP sau đây:

  • HTTP status 400 (Bad request) – thiếu tham số hoặc yêu cầu 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 đề ủy quyền không hợp lệ.
  • HTTP status 403 (Forbidden) – tiêu đề ủy 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) – không sử dụng được dịch vụ. Thử lại yêu cầu bằng thuật toán thời gian đợi luỹ thừa.