Sử dụng API REST 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 máy khách gốc, nhưng có một số trường hợp việc gọi trực tiếp API REST sẽ hữu ích.

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

  • Truy cập Cloud Firestore 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), trong đó không thể chạy thư viện máy khách hoàn chỉnh.
  • Tự động hóa 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 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à ủy quyền

Để xác thực, API REST của Cloud Firestore 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 bạn cung cấp ảnh hưởng đến ủy quyền yêu cầu của bạn:

  • Sử dụng mã thông báo ID 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 yêu cầu có được ủy 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ư 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 ủy quyền hay không.

Làm việc với mã thông báo ID Firebase

Bạn có thể nhận được mã thông báo ID Firebase theo hai cách:

Bằng cách truy xuất mã thông báo ID Firebase của người dùng, bạn có thể thay mặt người dùng thực hiện 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 ID Firebase và đối với các yêu cầu chưa được xác thực, Cloud Firestore sử dụng Quy tắc bảo mật Cloud Firestore của bạn để xác định xem yêu cầu có được ủy 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 khách API của Google hoặc bằng cách làm theo các bước trong Sử dụng OAuth 2.0 cho ứng dụng 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 tới API REST của 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 Google Identity OAuth 2.0, 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 của bạn thay vì một người dùng cá nhân. Cloud Firestore cho phép những 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 yêu cầu có được ủy 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ã thông báo truy cập

Sau khi bạn nhận được mã thông báo ID Firebase hoặc mã thông báo Google Identity OAuth 2.0, hãy chuyển mã đó đến điểm cuối 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ả các điểm cuối API REST đều tồn tại dưới URL cơ sở https://firestore.googleapis.com/v1/ .

Để tạo đường dẫn đến tài liệu có ID LA ở cities thu thập 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 nó 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 API REST là sử dụng API Explorer , API này tự động tạo mã thông báo Google Identity OAuth 2.0 và cho phép bạn kiểm tra API.

phương pháp

Dưới đây là mô tả ngắn gọn về hai nhóm phương pháp quan trọng nhất. Để có 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 hành động trên các chỉ mục như tạo chỉ mục mới, vô hiệu hóa chỉ mục hiện có hoặc liệt kê tất cả các chỉ mục hiện tại. Hữu ích cho việc tự động hóa việc di chuyển cấu trúc dữ liệu hoặc đồng bộ hóa các chỉ mục giữa các dự án.

Đồng thời 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 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 trả về mã trạng thái HTTP 200 OK và dữ liệu được yêu cầu. Khi yêu cầu không thành công, API Cloud Firestore trả về mã trạng thái HTTP 4xx hoặc 5xx và phản hồi kèm theo thông tin về lỗi.

Bảng sau 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 Cloud Firestore REST và RPC. SDK Cloud Firestore và thư viện ứng dụng khách có thể không trả về các mã lỗi tương tự.

Mã lỗi chuẩn Sự miêu tả Hành động được đề xuất
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 phi giao dịch:
Hãy thử lại yêu cầu hoặc cấu trúc lại mô hình dữ liệu của bạn để giảm xung đột.

Đối với các yêu cầu trong giao dịch:
Hãy thử lại toàn bộ giao dịch hoặc cấu trúc lại mô hình dữ liệu của bạn để giảm sự tranh chấp.
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 mà không khắc phục được vấn đề.
DEADLINE_EXCEEDED Máy chủ Cloud Firestore xử lý yêu cầu đã vượt quá thời hạn. Hãy thử lại bằng cách sử dụng thời gian chờ theo cấp số nhân.
FAILED_PRECONDITION Yêu cầu không đáp ứng được một trong những điều kiện tiên quyết của nó. 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. 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 đượ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 Tham số yêu cầu bao gồm 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 mà không khắc phục được vấn đề.
NOT_FOUND Yêu cầu đã 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 đượ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 được vấn đề.
RESOURCE_EXHAUSTED Dự án đã vượt quá hạn ngạch hoặc năng lực của khu vực/đa khu vực. Xác minh rằng bạn không vượt quá hạn ngạch dự án của mình . Nếu bạn vượt quá hạn ngạch dự án, đừng thử lại khi chưa khắc phục được sự cố.

Nếu không, hãy thử lại với thời gian chờ theo cấp số nhân.
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 đượ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 thời gian chờ theo cấp số nhân.