@firebase-函数-kits/firestore-bigquery-export

流出一所云火炉收藏到 BigQuery. 这是流火炉 作为 npm 软件包的大查询防火基地扩展, 您会添加到自己的防火基地 函数编码库和部署.

每个文档被序列化并插入到 BigQuery 更改日志表. 失败通过 Cloud 任务队列写入缓冲( E)syncBigQuery并且现在 再审.

以下用语:a 代码库 是云函数源代码 火基地CLI作为单位部署. A 类 工具包 由 a 声明的此软件包 kit 输入 firebase.json。一个 实例 是套装的复制件, 拥有自己的 .env 和四项功能; 国家领导才能将每个实例作为 以实例 id 命名的代码库 .

安装

假设最新的防火基地CLI已经安装并签名,并且您 从您的 Firebase 项目目录( 包含 firebase.json· ; firebase init 创建),与您的工程相链接 (单位:千美元)firebase use <project-id>) (中文(简体) ). 您还需要云火店 “火焰计划”和“节点24”(22个或以后得到支持).

向导安装器 . 这创建了下面的代码库 function-kits/<kit-name>/, (中文(简体) ), 添加 kit 条目为 firebase.json,每个设置的提示,写 答案为: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>数字 :

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export@latest

它还要求 FUNCTION_DEFAULT_REGION。输入区域功能 将运行于( a)us-central1 页:1 nam5; 见 地区) (中文(简体) ).

你自己的密码库. 从 functions/ 目录 firebase init functions 创建、 安装工具包 + firebase-functions 财务报告和审定财务报表 firebase-admin 作为直接的依赖,对工具包使用的主要版本 (目前为7和14个)。 该套装的收缩包装 嵌入了自己的拷贝,这是CLI 看不到: 没有他们,部署就失败了 Couldn't find firebase-functions package in your source code。 。 。 .

npm install @firebase-function-kits/[email protected] firebase-functions@7 firebase-admin@14
npm install --save-dev typescript@5

需要的仪表

手无所取. 第一次部署时 国家情报组要求你确认这些 角色(This codebase uses declarative security … Continue? (y/N),则 创建工具包服务账户,提供这些工具,并启用API。 别 设置自定义运行时间服务账户.

没有终端(例如CI),没有人可以回答,所以确认 与 --force。它接受每分一秒,因此仅限于一个实例:

firebase deploy --only functions:<instance-id> --force

设置 EVENTARC_CHANNEL 还添加 roles/eventarc.publisher 财务报告和审定财务报表 eventarcpublishing.googleapis.com。对于另一个项目的数据集,赠款 该工具包的服务账户 bigquery.* 这里的角色。 对于一个CMEK数据集, 允许大查询服务账户访问您的 KMS 密钥 .

使用量

有了你自己的代码库,这种布局保持了代码库和实例 .env 输入 functions/ 目录 firebase init functions 创建 :

my-project/
  .firebaserc
  firebase.json
  functions/
    package.json    # "main": "lib/index.js", "engines": { "node": "24" }, "scripts": { "build": "tsc" }
    tsconfig.json   # compiles src/ to lib/
    .env
    src/index.ts

// functions/src/index.ts
export {
  fsexportbigquery, // Firestore trigger
  syncBigQuery, // retries failed writes from the queue
  initBigQuerySync, // creates BigQuery resources after the first deploy
  setupBigQuerySync, // updates them after later deploys
} from "@firebase-function-kits/firestore-bigquery-export";

# functions/.env — set these before the first deploy
COLLECTION_PATH=users
DATASET_ID=firestore_export
TABLE_ID=users
DATABASE_REGION=nam5          # your Firestore database's location
DATASET_LOCATION=us           # keep BigQuery data near the database
BACKUP_COLLECTION=users_bigquery_failures

在部署时,需要你放弃的任何安排(见 配置) (中文(简体) ). 无 BACKUP_COLLECTION,失败的行 每次重试都失败了.

部署

在那个 functions 条目 firebase init 创建, 添加 kit 财务报告和审定财务报表 instances 财务报告和审定财务报表 删除 codebase 联合国 kit 条目不能有一个:

{
  "functions": [
    {
      "source": "functions",
      "kit": "firestore-bigquery-export",
      "instances": { "default": "functions" },
      "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"]
    }
  ]
}

kit 是您选择的任何名称( 最多40个小写字母, 数字, _, (中文(简体) ), -) (中文(简体) ). instances 将每个实例 id 映射到持有它的目录 .env函数 名称得到一个 kit-<instance-id>- 前缀,所以这个部署 kit-default-fsexportbigquery 诸如来. 使用密码库的指令 证明.

firebase deploy --only functions                 # all instances
firebase deploy --only functions:<instance-id>   # one instance

与 最新消息 火基地CLI. 旧版本可能无法部署 装有问题或部署有问题.

检查它的工作原理. 第一个部署运行 initBigQuerySync创建 数据集,其中包含 <TABLE_ID>_raw_changelog 表格(每起变化一行)和a <TABLE_ID>_raw_latest 视图(每个文档的当前状态)。 这需要一个 分钟或两分钟; 等 firebase functions:log --only kit-<instance-id>-initBigQuerySync 显示视图。 然后,在 基地控制台,将文档添加到  COLLECTION_PATH 藏书。 与 .env 从 使用量,添加 这个给 users数字 :

Document ID: alice
Fields:      name (string) = Alice
             age (number)  = 30

然后运行这个在 大查询控制台数字 :

SELECT document_id, operation, data, timestamp
FROM `<project-id>.<DATASET_ID>.<TABLE_ID>_raw_changelog`
ORDER BY timestamp DESC LIMIT 10

举例来说,表格是 <project-id>.firestore_export.users_raw_changelog,最新的一行有 document_id alice, (中文(简体) ), operation CREATE 财务报告和审定财务报表 data {"name":"Alice","age":30}。 。 。 .

该行可以花一分钟出现。 如果不见了,就等着 firebase functions:log --only kit-<instance-id>-fsexportbigquery 显示 Firestore event received by onDocumentWritten trigger (单位:千美元) LOG_LEVEL=info),然后再次查询.

配置

在实例中设置 .env (或 .env.<project-id>) (中文(简体) ). 如果设置 不在那里,部署要求你 提出默认,并保存你的 回复 .env.<project-id>。 。 。 .

一个设置 没有 在“可以是空白的”下 无法在一条线上部署 DATASET_ID=。给出一个值,或者删除行并回答提示.

多个实例

每个实例增加一个条目,每个条目都有自己的配置目录和 .env。 。 。 . 整个项目必须具有独特性.

"instances": { "users": "instances/users", "orders": "instances/orders" }

活动

与 EVENTARC_CHANNEL 设置, 函数发布 onStart 财务报告和审定财务报表 onError 从 触发和 onSuccess 从 syncBigQuery。每次活动在 两者 firebase.extensions.firestore-bigquery-export.v1.* 和扩展名 遗产 firebase.extensions.firestore-counter.v1.*; 写出新的触发器 第一个. EXT_SELECTED_EVENTS 按确切类型过滤,包括遗留副本. 从扩展导出的一个配置带有其 EXT_SELECTED_EVENTS 结束了,所以 请检查date=中的日期值 (帮助).

规定

initBigQuerySync 第一次部署后运行 setupBigQuerySync 之后 后面的,创建或更新数据集、表格和视图(15次尝试,60次) (原始内容存档于2017-09-21). Reference. 没有更改的调用被跳过,同样 setupBigQuerySync。写作从不创建资源:如果缺少,写作 失败到队列和备份收藏,直到生命周期任务运行.

要逐一运行,请从您的代码库目录中运行此选项 firebase-admin 安装和应用程序默认证书gcloud auth application-default login) (中文(简体) ). 惠璶 roles/cloudtasks.enqueuer附加时 roles/iam.serviceAccountUser 该工具箱的服务账户上 任务; KIT_SA 看这个账户:

export GOOGLE_CLOUD_PROJECT=<project-id> FUNCTION_REGION=us-central1
export KIT_SA=$(gcloud functions describe kit-<instance-id>-setupBigQuerySync \
  --region "$FUNCTION_REGION" --format 'value(serviceConfig.serviceAccountEmail)')
node -e '
const { initializeApp } = require("firebase-admin/app");
const { getFunctions } = require("firebase-admin/functions");
initializeApp({ serviceAccountId: process.env.KIT_SA });
getFunctions()
  .taskQueue("locations/'"$FUNCTION_REGION"'/functions/kit-<instance-id>-setupBigQuerySync")
  .enqueue({})
  .then(() => console.log("enqueued"));
'

处理失败

1. 触发器插入行内线. 如果失败, 行将被写入 BACKUP_COLLECTION (设定时) 更改顺序在 syncBigQuery。 。 。 .
2. syncBigQuery 尝试最多5次,至少60多次,然后写信给 BACKUP_COLLECTION 每次尝试失败后。 上次之后的任务就是 掉下来了 如果每个案子都忙 Cloud Run都用429来拒绝 在工具包的代码运行前,所以没有写入备份行.
3. 如果队列也失败, 触发器会记录出错, 发布 onError 放弃吧 活动没有重新交付.

备份文档以事件 ID 键入, 更改日志列下方 json。装入这些 json 对象与更改日志的图案放在临时表格中 (例如,导出收藏和 bq load 页:1 json 页:1 有些人是 被后来成功的失败所留下, 所以把它们与反联合起来 event_id数字 :

MERGE `<project-id>.<dataset>.<table>_raw_changelog` AS target
USING `<project-id>.<dataset>.<backup-temp-table>` AS backup
ON target.event_id = backup.event_id
WHEN NOT MATCHED THEN
  INSERT (timestamp, event_id, document_name, document_id, operation, data, old_data)
  VALUES (backup.timestamp, backup.event_id, backup.document_name,
          backup.document_id, backup.operation, backup.data, backup.old_data)

与 WILDCARD_IDS=true,添加 path_params 名单。 有习惯 分区字段,添加您 TIME_PARTITIONING_FIELD 栏。 譬如说, 双方和 TIME_PARTITIONING_FIELD=created_at数字 :

MERGE `<project-id>.<dataset>.<table>_raw_changelog` AS target
USING `<project-id>.<dataset>.<backup-temp-table>` AS backup
ON target.event_id = backup.event_id
WHEN NOT MATCHED THEN
  INSERT (timestamp, event_id, document_name, document_id, operation, data, old_data,
          path_params, created_at)
  VALUES (backup.timestamp, backup.event_id, backup.document_name,
          backup.document_id, backup.operation, backup.data, backup.old_data,
          backup.path_params, backup.created_at)

限制, 全部与扩展共享 :

• 插入前的失败( 例如损坏) TRANSFORM_FUNCTION没有 备份.
• 超过 1 MB 的更改无法被排序 . EXCLUDE_OLD_DATA=yes 将更新减半 载荷.
• 更改日志可以包含重复 event_ids;最新视图为: 不受影响.
• 删除或移动函数时,其云任务队列会作为 DISABLED。 。 。 .

从扩展名移出

从您的 Firebase 项目目录中运行迁移, 命名扩展名 实例以替换(无 --ext-instance它让你选一个:

firebase ext:migrate --ext-instance <instance-id>

它输出实例的配置,部署工具包,然后提议 解开分机 在新触发器暖和时写入 也没有出口者。 为了避免空档,对未安装的提示回答否,确认 工具箱记录每封信(见 看有没有用),然后卸载:

firebase ext:uninstall <instance-id> --immediate

一次运行两者都是安全的: 在共享事件 ID 上进行大查询 (尽最大努力),最新的观点不会受到任何重复的影响.

要恢复已丢失的写入, 请重新导入 fs-bq-import-collection, (中文(简体) ), 指向工具包的数据集和表格前缀,而写入则被暂停。 这个 导入每个文档的当前值为 IMPORT 行; 删除 替换的更新无法恢复 .

从流火炉到大查询扩展的区别

• 地区. 扩展的安装时云函数位置已消失. 见 地区。 。 。 .
• DATASET_LOCATION 可更改,但只有在数据集是 创建。 移动,设置一个新的 DATASET_ID 再来回填.
• 没有伴行工具. fs-bq-import-collection, (中文(简体) ), gen-schema-view 编辑 跨项目的赠款脚本留在扩展存储库中,并就 工具箱的桌子.
• 失败 onStart 发布 只日志警告; 扩展失败 执行.
• 相同的运行时间设置 . 货币 1, 扩展大小 CPU, 仅内部 触发入侵、540次任务超时、100起触发事件和500起 syncBigQuery (约84 vCPU of regional Cloud Run配额). 提升 setGlobalOptions({ maxInstances }) 更多的触发量.
• ext:migrate 带有全球选项. 它生成的条目文件应用 扩展的内存、 超时、 侵入和实例限制 setGlobalOptions只要一个功能没有设置它自己的。 检查 EXT_MIGRATED_SYSTEM_* 数值 .env。 。 。 .

地区

向该区域部署的职能来自 DATABASE_REGION区域 现在的位置, nam5 财务报告和审定财务报表 nam7 改为 us-central1, (中文(简体) ), eur3 改为 europe-west1。 。 。 . 触发器仍在数据库所在区域起火. 设定 DATABASE_REGION 内 .env 第一次部署之前; 部署时给出的值仅适用于 从下一个部署.

与 DATABASE_REGION= 空白, 函数进入 FUNCTION_DEFAULT_REGION 在安装器或迁移生成的代码库中,以其他方式 us-central1 (或它们目前的区域)。 更改区域删除并重新创建函数 和他们的队列.

API 表面

• 主要条目 (单位:千美元)@firebase-function-kits/firestore-bigquery-export: 四个功能和所有从库条目。 还进口 登记 afterFirstDeploy 编号 : afterRedeploy 任务.
• 图书馆条目 (单位:千美元)@firebase-function-kits/firestore-bigquery-export/lib: handleDocumentWrite 财务报告和审定财务报表 handleSyncBigQueryTask 用于登记触发器 你自己,还有 ExportConfig, (中文(简体) ), ResolvedExportConfig, (中文(简体) ), resolveExportConfig, (中文(简体) ), toTrackerConfig, (中文(简体) ), ViewType, (中文(简体) ), DocumentWriteEvent, (中文(简体) ), HandlerContext, (中文(简体) ), SerializedDocumentChange, (中文(简体) ), ChangeType类型 ChangeTrackerConfig 财务报告和审定财务报表 FirestoreBigQueryEventHistoryTracker。 。 。 .

许可证

阿帕奇 - 2.0