如何在Firestore REST API请求中携带自定义Firebase App Check令牌？

核心要求 #

Firestore REST API接受请求时，必须同时携带自定义App Check令牌和对应的身份验证凭据（按需），两者缺一不可（除非安全规则放宽限制，但不推荐）。

步骤1：配置请求头 #

需要添加两个关键请求头：

• X-Firebase-AppCheck：值直接填你获取到的自定义App Check令牌（无需Bearer前缀）
• Authorization：
  • 若为用户侧请求：值为Bearer <用户ID令牌>（从Firebase Auth获取的用户身份令牌）
  • 若为服务器侧无用户请求：可使用服务账号生成的访问令牌，或确保自定义App Check令牌符合Firebase的JWT规范

步骤2：构造并发送请求 #

以下是常见操作的cURL示例，替换占位符为你的实际信息：

读取单个文档 #

curl "https://firestore.googleapis.com/v1/projects/[你的项目ID]/databases/(default)/documents/[集合名]/[文档ID]" \
  -H "X-Firebase-AppCheck: [你的自定义App Check令牌]" \
  -H "Authorization: Bearer [用户ID令牌]"

创建新文档（自动生成ID） #

curl -X POST "https://firestore.googleapis.com/v1/projects/[你的项目ID]/databases/(default)/documents/[集合名]" \
  -H "X-Firebase-AppCheck: [你的自定义App Check令牌]" \
  -H "Authorization: Bearer [用户ID令牌]" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "username": {"stringValue": "johndoe"},
      "email": {"stringValue": "john@example.com"}
    }
  }'

更新现有文档 #

curl -X PATCH "https://firestore.googleapis.com/v1/projects/[你的项目ID]/databases/(default)/documents/[集合名]/[文档ID]?updateMask.fieldPaths=username" \
  -H "X-Firebase-AppCheck: [你的自定义App Check令牌]" \
  -H "Authorization: Bearer [用户ID令牌]" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "username": {"stringValue": "johndoe_updated"}
    }
  }'

步骤3：验证与排错 #

• 令牌有效性：确保自定义App Check令牌是符合Firebase JWT规范的，包含正确的aud（你的项目ID）、exp（未过期）等声明
• 安全规则：Firestore规则需验证App Check，比如添加allow read, write: if request.app != null;，确保只有带有效App Check令牌的请求能访问
• 错误排查：
  • 403：检查令牌是否过期、请求头格式是否正确、安全规则是否允许访问
  • 401：检查Authorization头的用户/服务账号令牌是否有效
  • 400：检查请求体格式是否符合Firestore REST的字段规范

内容的提问来源于stack exchange，提问作者lurkerCha