Gửi thông báo bằng API HTTP v1 của FCM

Khi sử dụng API HTTP v1 của FCM, bạn có thể tạo yêu cầu gửi thông báo và gửi yêu cầu đó đến các loại mục tiêu sau:

  • Tên chủ đề
  • Tình trạng
  • Mã thông báo đăng ký thiết bị
  • Tên nhóm thiết bị (chỉ giao thức)

Bạn có thể gửi thông báo kèm theo tải trọng thông báo được tạo từ các trường xác định trước, tải trọng dữ liệu của các trường do người dùng xác định hoặc thông báo chứa cả hai loại tải trọng. Hãy xem Các loại thông báo để biết thêm thông tin.

Cấp quyền cho yêu cầu gửi HTTP v1

Tuỳ thuộc vào thông tin chi tiết về môi trường máy chủ, hãy sử dụng kết hợp các chiến lược sau để cấp quyền cho các yêu cầu của máy chủ đối với các dịch vụ của Firebase:

  • Thông tin xác thực mặc định của ứng dụng trên Google (ADC)
  • Tệp JSON tài khoản dịch vụ
  • Mã truy cập OAuth 2.0 có thời hạn ngắn bắt nguồn từ tài khoản dịch vụ

Nếu ứng dụng của bạn đang chạy trên Compute Engine, Google Kubernetes Engine, App Engine, hoặc Cloud Functions (bao gồm cả Cloud Functions for Firebase), hãy sử dụng Thông tin xác thực mặc định của ứng dụng (ADC). ADC sử dụng tài khoản dịch vụ mặc định hiện có của bạn để lấy thông tin xác thực nhằm cấp quyền cho các yêu cầu và ADC cho phép kiểm thử linh hoạt ở cục bộ thông qua biến môi trường GOOGLE_APPLICATION_CREDENTIALS. Để tự động hoá hoàn toàn quy trình cấp quyền, hãy sử dụng ADC cùng với các thư viện máy chủ của SDK dành cho quản trị viên.

Nếu ứng dụng của bạn đang chạy trên môi trường máy chủ không phải của Google, bạn cần tải tệp JSON tài khoản dịch vụ xuống từ dự án Firebase. Miễn là bạn có quyền truy cập vào hệ thống tệp chứa tệp khoá riêng tư, bạn có thể sử dụng biến môi trường GOOGLE_APPLICATION_CREDENTIALS để cấp quyền cho các yêu cầu bằng những thông tin xác thực thu được theo cách thủ công này. Nếu không có quyền truy cập vào tệp như vậy, bạn phải tham chiếu tệp tài khoản dịch vụ trong mã của mình. Bạn nên thực hiện việc này một cách cẩn thận do nguy cơ lộ thông tin xác thực.

Cung cấp thông tin xác thực bằng ADC

Thông tin xác thực mặc định của ứng dụng trên Google (ADC) sẽ kiểm tra thông tin xác thực của bạn theo thứ tự sau:

  1. ADC kiểm tra xem biến môi trường GOOGLE_APPLICATION_CREDENTIALS đã được thiết lập hay chưa. Nếu biến này được thiết lập, ADC sẽ sử dụng tệp tài khoản dịch vụ mà biến này trỏ đến.

  2. Nếu biến môi trường không được thiết lập, ADC sẽ sử dụng tài khoản dịch vụ mặc định mà Compute Engine, Google Kubernetes Engine, App Engine, và Cloud Functions cung cấp cho các ứng dụng chạy trên các dịch vụ đó.

  3. Nếu ADC không thể sử dụng một trong hai thông tin xác thực ở trên, hệ thống sẽ gửi thông báo lỗi.

Ví dụ về mã SDK dành cho quản trị viên sau đây minh hoạ chiến lược này. Ví dụ này không chỉ định rõ thông tin xác thực của ứng dụng. Tuy nhiên, ADC có thể tìm thấy thông tin xác thực một cách ngầm ẩn miễn là biến môi trường được thiết lập hoặc miễn là ứng dụng đang chạy trên Compute Engine, Google Kubernetes Engine, App Engine, hoặc Cloud Functions.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Bắt đầu

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}
init.go

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Cung cấp thông tin xác thực theo cách thủ công

Các dự án Firebase hỗ trợ tài khoản dịch vụ của Google. Bạn có thể sử dụng các tài khoản này để gọi các API máy chủ của Firebase từ máy chủ ứng dụng hoặc môi trường đáng tin cậy. Nếu đang phát triển mã cục bộ hoặc triển khai ứng dụng tại chỗ, bạn có thể sử dụng thông tin xác thực thu được bằng tài khoản dịch vụ này để cấp quyền cho các yêu cầu của máy chủ.

Bạn có thể xem tất cả tài khoản dịch vụ cho dự án Firebase trong phần cài đặt Settings > Service accounts tab.

Để xác thực tài khoản dịch vụ và cấp quyền truy cập vào các dịch vụ của Firebase, bạn phải tạo tệp khoá riêng tư ở định dạng JSON.

Cách tạo tệp khoá riêng tư cho tài khoản dịch vụ:

  1. Trong bảng điều khiển Firebase, hãy chuyển đến phần Settings (Cài đặt) > thẻ Service accounts (Tài khoản dịch vụ).

  2. Nhấp vào Generate New Private Key, sau đó xác nhận bằng cách nhấp vào Generate Key.

  3. Lưu trữ tệp JSON chứa khoá một cách an toàn.

Khi cấp quyền thông qua tài khoản dịch vụ, bạn có 2 lựa chọn để cung cấp thông tin xác thực cho ứng dụng. Bạn có thể thiết lập biến môi trường GOOGLE_APPLICATION_CREDENTIALS hoặc có thể truyền rõ ràng đường dẫn đến khoá tài khoản dịch vụ trong mã. Lựa chọn đầu tiên an toàn hơn và bạn nên sử dụng lựa chọn này.

Cách thiết lập biến môi trường:

Thiết lập biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn tệp của tệp JSON chứa khoá tài khoản dịch vụ. Biến này chỉ áp dụng cho phiên shell hiện tại. Vì vậy, nếu bạn mở một phiên mới, hãy thiết lập lại biến này.

Linux hoặc macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Với PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Sau khi bạn hoàn tất các bước ở trên, Thông tin xác thực mặc định của ứng dụng (ADC) có thể xác định ngầm ẩn thông tin xác thực của bạn, cho phép bạn sử dụng thông tin xác thực của tài khoản dịch vụ khi kiểm thử hoặc chạy trong môi trường không phải của Google.

Sử dụng thông tin xác thực để tạo mã truy cập

Trừ phi bạn đang sử dụng Firebase Admin SDK, SDK này tự động xử lý việc cấp quyền, bạn cần tạo mã truy cập và thêm mã đó để gửi yêu cầu.

Sử dụng thông tin xác thực của Firebase cùng với Thư viện xác thực của Google cho ngôn ngữ bạn muốn để truy xuất mã truy cập OAuth 2.0 có thời hạn ngắn:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}
index.js

Trong ví dụ này, thư viện ứng dụng API của Google sẽ xác thực yêu cầu bằng mã thông báo cho trang web theo chuẩn JSON (JWT). Để biết thêm thông tin, hãy xem bài viết Mã thông báo cho trang web theo chuẩn JSON.

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token
messaging.py

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}
Messaging.java

Sau khi mã truy cập của bạn hết hạn, phương thức làm mới mã thông báo sẽ tự động được gọi để truy xuất mã truy cập đã cập nhật.

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

Cách thêm mã truy cập vào tiêu đề của yêu cầu HTTP:

Thêm mã thông báo làm giá trị của tiêu đề Authorization theo định dạng Authorization: Bearer <access_token>:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}
messaging.py

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
FirebaseMessagingSnippets.java

Cấp quyền cho tài khoản dịch vụ từ một dự án khác

Bạn có thể gửi thông báo cho một dự án ("dự án mục tiêu") trong khi sử dụng mã thông báo OAuth 2.0 được tạo từ tài khoản dịch vụ trong một dự án khác ("dự án người gửi"). Do đó, bạn có thể tập trung quản lý tài khoản dịch vụ trong một dự án trong khi gửi thông báo thay mặt cho các dự án khác. Để tìm hiểu cách thực hiện việc này, hãy làm theo các bước sau:

  1. Trong dự án người gửi, hãy đảm bảo rằng bạn đã bật API Giải pháp gửi thông báo qua đám mây của Firebase. Kiểm tra xem API này đã được bật hay chưa trong bảng điều khiển Firebase bằng cách chuyển đến phần cài đặt Settings > General. Sau đó, hãy nhấp vào thẻ Gửi thông báo qua đám mây.

  2. Trong dự án người gửi, hãy tạo a tài khoản dịch vụ.

  3. Trong dự án mục tiêu, hãy chỉ định vai trò Quản trị viên API Giải pháp gửi thông báo qua đám mây của Firebase cho địa chỉ email của tài khoản dịch vụ. Bạn thực hiện việc này trong trang IAM & Admin > IAM của bảng điều khiển Google Cloud. Vai trò này cho phép tài khoản dịch vụ từ dự án người gửi gửi thông báo đến dự án mục tiêu.

  4. Tạo mã truy cập OAuth 2.0 cho tài khoản dịch vụ trong dự án người gửi. Bạn có thể thực hiện việc này bằng một trong các cách sau:

    • Tải tệp JSON khoá tài khoản dịch vụ xuống và sử dụng tệp đó.
    • Sử dụng Workload Identity nếu dịch vụ của bạn đang chạy trên Google Cloud.

  5. Sử dụng mã truy cập thu được trong tiêu đề Authorization của yêu cầu gửi. Bạn phải gửi yêu cầu đến điểm cuối HTTP v1 cho dự án mục tiêu:

      POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

Gửi thông báo đến các thiết bị cụ thể

Để gửi đến một thiết bị cụ thể, hãy truyền mã thông báo đăng ký của thiết bị như minh hoạ.

Kiến trúc chuyển trạng thái đại diện (REST)

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Lệnh cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Khi thành công, phản hồi của API HTTP v1 là một đối tượng JSON chứa mã thông báo:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Gửi thông báo kiểm thử bằng API HTTP v1 của FCM

Phần này mô tả cách gửi thông báo kiểm thử bằng API HTTP v1 của FCM.

URL yêu cầu HTTP

Yêu cầu bao gồm một yêu cầu POST qua HTTP đến mục tiêu đã chỉ định (mã thông báo đăng ký, chủ đề hoặc điều kiện) tại URL sau:

POST https://fcm.googleapis.com/v1/projectId/messages:send

Mẫu JSON yêu cầu HTTP hoàn chỉnh

Sau đây là ví dụ hoàn chỉnh cho thấy cách đăng thông báo trong yêu cầu POST qua HTTP:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://cat.10515.net/1.jpg"
    }
  }
}

Chạy

Nhấp vào Run (Chạy) để dùng thử mẫu trong API Explorer (Trình khám phá API).