Sử dụng API REST của Cloud Firestore

Mặc dù cách dễ nhất để sử dụng Cloud Firestore là sử dụng một trong các thư viện ứng dụng gốc, nhưng có một số trường hợp bạn nên gọi trực tiếp API REST.

API REST có thể hữu ích cho các trường hợp sử dụng sau:

  • Truy cập vào Cloud Firestore từ một môi trường bị hạn chế về tài nguyên, chẳng hạn như thiết bị Internet vạn vật (IoT) không thể chạy thư viện ứng dụng đầy đủ.
  • Tự động hoá việc quản trị cơ sở dữ liệu hoặc truy xuất siêu dữ liệu cơ sở dữ liệu chi tiết.

Nếu bạn đang dùng một ngôn ngữ được hỗ trợ gRPC, hãy cân nhắc dùng RPC API thay vì API REST.

Xác thực và uỷ quyền

Để xác thực, API REST Cloud Firestore chấp nhận mã thông báo giá trị nhận dạng Firebase Authentication hoặc mã thông báo Google Identity OAuth 2.0. Mã thông báo mà bạn cung cấp ảnh hưởng đến việc uỷ quyền yêu cầu của bạn:

  • Sử dụng mã thông báo nhận dạng Firebase để xác thực các yêu cầu của người dùng ứng dụng. Đối với các yêu cầu này, Cloud Firestore sử dụng Cloud Firestore Security Rules để xác định xem một yêu cầu có được uỷ quyền hay không.

  • Sử dụng mã thông báo Google Identity OAuth 2.0 và tài khoản dịch vụ để xác thực các yêu cầu từ ứng dụng của bạn, chẳng hạn như các yêu cầu quản trị cơ sở dữ liệu. Đối với các yêu cầu này, Cloud Firestore sử dụng Quản lý danh tính và quyền truy cập (IAM) để xác định xem yêu cầu có được uỷ quyền hay không.

Làm việc với mã thông báo nhận dạng Firebase

Bạn có thể lấy mã thông báo mã nhận dạng Firebase theo hai cách:

Bằng cách truy xuất mã thông báo mã nhận dạng Firebase của người dùng, bạn có thể thay mặt người dùng gửi yêu cầu.

Đối với các yêu cầu được xác thực bằng mã thông báo mã nhận dạng Firebase và đối với các yêu cầu chưa được xác thực, Cloud Firestore sử dụng Cloud Firestore Security Rules để xác định xem một yêu cầu có được uỷ quyền hay không.

Làm việc với mã thông báo Google Identity OAuth 2.0

Bạn có thể tạo mã thông báo truy cập bằng cách sử dụng tài khoản dịch vụ với Thư viện ứng dụng Google API hoặc bằng cách làm theo các bước trong phần Sử dụng OAuth 2.0 cho ứng dụng từ máy chủ đến máy chủ. Bạn cũng có thể tạo mã thông báo bằng công cụ dòng lệnh gcloud và lệnh gcloud auth application-default print-access-token.

Mã thông báo này phải có phạm vi sau để gửi yêu cầu đến API REST Cloud Firestore:

  • https://www.googleapis.com/auth/datastore

Nếu bạn xác thực các yêu cầu của mình bằng tài khoản dịch vụ và mã thông báo OAuth 2.0 của Google Identity, thì Cloud Firestore sẽ giả định rằng các yêu cầu của bạn thay mặt cho ứng dụng của bạn thay vì một người dùng cá nhân. Cloud Firestore cho phép các yêu cầu này bỏ qua các quy tắc bảo mật của bạn. Thay vào đó, Cloud Firestore sử dụng IAM để xác định xem một yêu cầu có được uỷ quyền hay không.

Bạn có thể kiểm soát quyền truy cập của tài khoản dịch vụ bằng cách chỉ định Cloud Firestore vai trò IAM.

Xác thực bằng mã truy cập

Sau khi bạn lấy mã thông báo mã nhận dạng Firebase hoặc mã thông báo OAuth 2.0 của Google Identity, hãy truyền mã đó đến các điểm cuối Cloud Firestore dưới dạng tiêu đề Authorization được đặt thành Bearer {YOUR_TOKEN}.

Thực hiện lệnh gọi REST

Tất cả các điểm cuối API REST đều nằm trong URL cơ sở https://firestore.googleapis.com/v1/.

Để tạo đường dẫn đến một tài liệu có mã LA trong bộ sưu tập cities trong dự án YOUR_PROJECT_ID, bạn sẽ sử dụng cấu trúc sau.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Để tương tác với đường dẫn này, hãy kết hợp đường dẫn này với URL API cơ sở.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Cách tốt nhất để bắt đầu thử nghiệm với API REST là sử dụng API Explorer (Trình khám phá API). Công cụ này sẽ tự động tạo mã thông báo OAuth 2.0 của Google Identity và cho phép bạn kiểm tra API.

Phương thức

Dưới đây là nội dung mô tả ngắn gọn về hai nhóm phương thức quan trọng nhất. Để biết danh sách đầy đủ, hãy xem tài liệu tham khảo API REST hoặc sử dụng API Explorer.

v1.projects.databases.documents

Thực hiện các thao tác CRUD trên tài liệu, tương tự như các thao tác được nêu trong hướng dẫn thêm dữ liệu hoặc lấy dữ liệu.

v1.projects.databases.collectionGroups.indexes

Thực hiện các thao tác trên chỉ mục như tạo chỉ mục mới, tắt chỉ mục hiện có hoặc liệt kê tất cả chỉ mục hiện tại. Hữu ích cho việc tự động hoá quá trình di chuyển cấu trúc dữ liệu hoặc đồng bộ hoá các chỉ mục giữa các dự án.

Ngoài ra, cho phép truy xuất siêu dữ liệu tài liệu, chẳng hạn như danh sách tất cả các trường và bộ sưu tập phụ cho một tài liệu nhất định.

Mã lỗi

Khi yêu cầu Cloud Firestore thành công, API Cloud Firestore sẽ trả về mã trạng thái HTTP 200 OK và dữ liệu được yêu cầu. Khi một yêu cầu không thành công, API Cloud Firestore sẽ trả về một mã trạng thái HTTP 4xx hoặc 5xx và một phản hồi có thông tin về lỗi.

Bảng sau đây liệt kê các hành động được đề xuất cho từng mã lỗi. Các mã này áp dụng cho API RPC và REST Cloud Firestore. SDK và thư viện ứng dụng Cloud Firestore có thể không trả về các mã lỗi này.

Mã lỗi chuẩn Mô tả Việc nên làm
ABORTED Yêu cầu này đã xung đột với một yêu cầu khác. Đối với một giao dịch không có giao dịch:
Thử lại yêu cầu hoặc định cấu trúc lại mô hình dữ liệu để giảm xung đột.

Đối với các yêu cầu trong một giao dịch:
Thử lại toàn bộ giao dịch hoặc định cấu trúc lại mô hình dữ liệu để giảm xung đột.
ALREADY_EXISTS Yêu cầu đã cố gắng tạo một tài liệu đã tồn tại. Đừng thử lại nếu bạn chưa khắc phục vấn đề.
DEADLINE_EXCEEDED Máy chủ Cloud Firestore xử lý yêu cầu đã vượt quá thời hạn. Thử lại bằng thuật toán thời gian đợi luỹ thừa.
FAILED_PRECONDITION Yêu cầu không đáp ứng một trong các điều kiện tiên quyết. Ví dụ: một yêu cầu truy vấn có thể yêu cầu một chỉ mục chưa được xác định. Hãy xem trường thông báo trong phản hồi lỗi để biết điều kiện tiên quyết không thành công. Đừng thử lại nếu bạn chưa khắc phục vấn đề.
INTERNAL Máy chủ Cloud Firestore trả về lỗi. Đừng thử lại yêu cầu này nhiều lần.
INVALID_ARGUMENT Một tham số yêu cầu có giá trị không hợp lệ. Xem trường thông báo trong phản hồi lỗi để biết giá trị không hợp lệ. Đừng thử lại nếu bạn chưa khắc phục vấn đề.
NOT_FOUND Yêu cầu này đã cố gắng cập nhật một tài liệu không tồn tại. Đừng thử lại nếu bạn chưa khắc phục vấn đề.
PERMISSION_DENIED Người dùng không được phép thực hiện yêu cầu này. Đừng thử lại nếu bạn chưa khắc phục vấn đề.
RESOURCE_EXHAUSTED Dự án đã vượt quá hạn mức hoặc dung lượng theo khu vực/đa khu vực. Xác minh rằng bạn không vượt quá hạn mức dự án. Nếu bạn đã vượt quá hạn mức của dự án, đừng thử lại mà không khắc phục vấn đề.

Nếu không, hãy thử lại bằng thuật toán thời gian đợi luỹ thừa.
UNAUTHENTICATED Yêu cầu không bao gồm thông tin xác thực hợp lệ. Đừng thử lại nếu bạn chưa khắc phục vấn đề.
UNAVAILABLE Máy chủ Cloud Firestore trả về lỗi. Hãy thử lại bằng cách sử dụng thuật toán thời gian đợi luỹ thừa.