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 thư viện ứng dụng gốc, có một số trường hợp mà bạn nên hãy 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), trong đó việc vận hành một ứng dụng hoàn chỉnh không thể.
  • 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 hỗ trợ gRPC, hãy cân nhắc việc sử dụng API RPC 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 ID 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 ả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 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 các 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 có yêu cầu nào hay không đã được uỷ quyền.

  • 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, 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, Các trường hợp sử dụng Cloud Firestore Quản lý danh tính và quyền truy cập (IAM) để xác định xem đã được uỷ quyền.

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ể thực hiện 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 mã Firebase và chưa được xác thực của bạn, 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.

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 sử dụng tài khoản dịch vụ có Thư viện ứng dụng API của Google hoặc làm theo các bước trong 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à gcloud auth application-default print-access-token.

Mã thông báo này phải có các phạm vi 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 của mình bằng tài khoản dịch vụ và Google Identity Mã thông báo OAuth 2.0, Cloud Firestore giả định rằng các yêu cầu của bạn hành động thay mặt thay vì một người dùng cá nhân. Cloud Firestore cho phép những yêu cầu này nhằm bỏ qua các quy tắc bảo mật của bạn. Thay vào đó, Cloud Firestore 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 Các vai trò trong dịch vụ quản lý danh tính và quyền truy cập (IAM) của Cloud Firestore.

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

Sau khi bạn nhận được mã thông báo mã Firebase hoặc OAuth 2.0 của Google Identity mã thông báo, hãy truyền mã đó đến các điểm cuối Cloud Firestore dưới dạng Authorization đã đặt tiêu đề 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/.

Cách 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 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) tự động tạo Google Identity Mã thông báo OAuth 2.0 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 đầ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 thêm dữ liệu hoặc hướng dẫn 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, vô hiệu hoá thuộc tính hiện có chỉ mục hoặc liệt kê tất cả chỉ mục hiện tại. Hữu ích khi tự động hoá cấu trúc dữ liệu di chuyển hoặc đồng bộ hoá chỉ mục giữa các dự án.

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à 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, Cloud Firestore API 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à 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ó áp dụng các mã này đến các API REST và RPC của Cloud Firestore. Cloud Firestore SDK và thư viện ứng dụng 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.