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 vẫn 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 trong 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 của vạn vật (IoT) mà 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 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, Cloud Firestore REST API chấp nhận mã thông báo mã nhận dạng Xác thực Firebase hoặc mã thông báo Google Identity OAuth 2.0. Mã thông báo mà bạn cung cấp sẽ ảnh hưởng đến việc uỷ quyền của yêu cầu:

  • Sử dụng mã thông báo mã Firebase để xác thực yêu cầu từ người dùng ứng dụng của bạn. Đối với những yêu cầu này, Cloud Firestore sử dụng Quy tắc bảo mật của Cloud Firestore để 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 OAuth 2.0 của Google Identity 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 những yêu cầu này, Cloud Firestore sử dụng giải pháp 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 mã nhận dạng Firebase

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

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

Đối với các yêu cầu được xác thực bằng mã thông báo giá trị 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 Quy tắc bảo mật của Cloud Firestore để 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ã truy cập bằng cách dùng tài khoản dịch vụ với Thư viện ứng dụng API của Google hoặc làm theo các bước trong bài viết 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 như sau để gửi yêu cầu đến API REST của Cloud Firestore:

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

Nếu bạn xác thự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, Cloud Firestore sẽ giả định rằng các yêu cầu của bạn hành động thay mặt cho ứng dụng 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 vai trò IAM của Cloud Firestore.

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 của Cloud Firestore dưới dạng tiêu đề Authorization được đặt thành Bearer {YOUR_TOKEN}.

Thực hiện cuộc gọi REST

Tất cả điểm cuối của API REST đều tồn tại 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á 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. Để 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 mộ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á việc di chuyển cấu trúc dữ liệu hoặc đồng bộ hoá 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 con của 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, Cloud Firestore API sẽ trả về một 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, Cloud Firestore API 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 các API REST và RPC của Cloud Firestore. Các SDK và thư viện ứng dụng trên Cloud Firestore có thể không trả về cùng một 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 cam kết phi giao dịch:
Hãy thử lại yêu cầu hoặc sắp xếp lại mô hình dữ liệu của bạn để giảm tình trạng 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 tranh chấp.
ALREADY_EXISTS Yêu cầu đã cố 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 này đã vượt quá thời hạn. Hãy thử lại bằng cách sử dụng thuật toán thời gian đợi luỹ thừa.
FAILED_PRECONDITION Yêu cầu không đáp ứng được một trong các điều kiện tiên quyết. Ví dụ: yêu cầu truy vấn có thể đòi hỏi 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 mà không khắc phục vấn đề.
INTERNAL Máy chủ Cloud Firestore trả về một lỗi. Đừng thử gửi lại yêu cầu này nhiều lần.
INVALID_ARGUMENT Thông số yêu cầu chứa 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 đã cố 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 nhiều 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 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 mà không khắc phục vấn đề.
UNAVAILABLE Máy chủ Cloud Firestore trả về một 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.