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

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

REST API 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 hạn chế tài nguyên, chẳng hạn như thiết bị Internet of Things (IoT), nơi không thể chạy một thư viện ứng dụng hoàn chỉnh.
  • Tự động hoá việc quản trị cơ sở dữ liệu hoặc truy xuất siêu dữ liệu chi tiết của cơ sở dữ liệu.

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

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

Để xác thực, REST API Cloud Firestore chấp nhận mã thông báo ID Firebase Authentication hoặc mã thông báo OAuth 2.0 của Google Identity. Mã thông báo mà bạn cung cấp sẽ ảnh hưởng đến việc uỷ quyền cho 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 những 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 phép hay không.

  • Sử dụng mã thông báo OAuth 2.0 của Google Identity và một 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ư yêu cầu quản trị cơ sở dữ liệu. Đối với những 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ể nhận mã thông báo nhận dạng Firebase theo hai cách:

Bằng cách truy xuất mã thông báo nhận dạng Firebase của người dùng, bạn có thể thay mặt người dùng đưa ra các 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 nhận dạng Firebase và các yêu cầu chưa được xác thực, Cloud Firestore sẽ sử dụng Cloud Firestore Security Rules của bạn để 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 OAuth 2.0 của Google Identity

Bạn có thể tạo mã 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 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 chứ không phải người dùng cá nhân. Cloud Firestore cho phép các yêu cầu này bỏ qua 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 Firestorevai trò IAM.

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

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

Thực hiện các 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ã nhận dạng LA trong tập hợ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 đó với URL cơ sở của API.

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 REST API là sử dụng API Explorer. 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ề 2 nhóm phương thức quan trọng nhất. Để xem danh sách đầy đủ, hãy xem tài liệu tham khảo về 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 nhận dữ liệu.

v1.projects.databases.collectionGroups.indexes

Thực hiện các thao tác trên chỉ mục, chẳng hạn như tạo chỉ mục mới, vô hiệu hoá 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á chỉ mục giữa các dự án.

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

Mã lỗi

Khi một 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ã trạng thái HTTP 4xx hoặc 5xx và một phản hồi chứa thông tin về lỗi.

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

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 cam kết không giao dịch:
Thử lại yêu cầu hoặc tái cấu trúc mô hình dữ liệu để giảm sự tranh chấp.

Đố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 tái cấu trúc mô hình dữ liệu để giảm sự tranh chấp.
ALREADY_EXISTS Yêu cầu này cố gắng tạo một tài liệu đã tồn tại. Đừng thử lại mà không 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 đáp ứng được. Đừng thử lại mà không khắc phục vấn đề.
INTERNAL Máy chủ Cloud Firestore đã trả về một 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ệ. Hãy 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 mà không 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 mà không 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 mà không khắc phục vấn đề.
RESOURCE_EXHAUSTED Dự án đã vượt quá hạn mức hoặc dung lượng của khu vực/nhiều 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 dự án, đừng thử lại mà không khắc phục vấn đề.

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