Gemini API 长篇写作任务怎么用 Webhook 接收完成通知

先确定通知后的处理边界

Webhook 的作用是通知你的服务“有任务需要处理”，不是直接把通知内容当成可发布文章。建议将生成任务、文章草稿和发布状态分开保存：任务只记录异步执行情况，草稿保存正文与编辑信息，发布状态只在人工或程序检查通过后改变。

• 为每次长篇写作生成本地 task_id，并保存 Gemini 侧返回的任务标识。
• 准备一个可被外部访问的 HTTPS 接收地址，并在部署环境保存访问日志。
• 在配置前核对当前官方文档中的 Webhook 创建方式、事件字段、认证机制和可订阅事件。
• 定义状态流转，例如 queued、notified、fetching、saved、reviewing、published、failed。

官方更新说明，Gemini API 的 Webhook 用于替代 Batch API 与长时间运行操作的轮询流程。资料包没有给出具体事件名称、请求头或签名字段，因此这些细节应以接入时的官方接口文档为准。

建立可追溯的任务表

不要只保存一条“已完成”标记。至少让本地记录能够回答：哪个文章任务收到通知、是否已取回结果、正文保存到了哪里、谁允许发布。

writing_jobs
- task_id
- provider_job_id
- article_id
- status
- result_version
- received_event_key
- raw_event_saved_at
- content_saved_at
- error_message

其中 received_event_key 用于去重。若官方事件提供唯一 ID，可记录该 ID；若没有，则由任务标识、事件类型和接收时间等稳定信息生成本地去重键。不要只按“文章 ID”去重，否则同一篇文章的重新生成任务可能被错误忽略。

按顺序处理完成事件

1. 接收 HTTP 请求后，先按官方规则验证请求来源或认证信息；验证失败立即拒绝，不进入写作流程。
2. 保存原始通知和接收时间，用于后续审计；日志中不要写入密钥或完整正文。
3. 读取任务标识，查询本地 writing_jobs。查不到任务时标为待人工处理，不要自动新建文章。
4. 检查去重键。已成功处理过的通知直接返回成功，避免重复保存或重复发布。
5. 将任务更新为 fetching，再按 Gemini API 当前文档获取该异步任务的最终结果。
6. 确认结果处于完成状态后，提取正文并写入草稿版本；保存结果来源、模型与任务标识。
7. 将草稿送入 reviewing，而不是直接发布。获取失败时记录错误并进入 failed，供后台重试。

接收端应尽快完成验证、入库和响应。耗时的结果拉取与正文检查可交给队列工作进程，避免通知方因超时再次投递同一事件。

以一篇批量长文为例

假设运营人员提交“整理产品资料并生成初稿”的任务，本地创建 task_id 为 write_20260908_001，并将 Gemini 任务标识关联到文章草稿 315。完成通知到达后，接收端只做入库和排队；工作进程再读取 write_20260908_001，获取最终结果，并创建草稿版本 2。

onWebhook(event):
  verifyWithOfficialRules(event)
  job = findJob(event.provider_job_id)
  if job is null:
    saveForManualReview(event)
    return success
  if eventAlreadyHandled(event):
    return success
  saveEvent(event)
  enqueue("fetch-writing-result", job.task_id)
  return success

onFetchWritingResult(taskId):
  job = loadJob(taskId)
  result = fetchProviderResult(job.provider_job_id)
  if result is not completed:
    markFailedOrRetry(job)
    return
  saveDraftVersion(job.article_id, result)
  markReviewing(job)

这里的 fetchProviderResult 是你的适配层，不应假设固定 SDK、固定接口路径或固定返回字段。升级 Gemini API 版本时，只调整适配层并用测试事件回归即可。

常见故障与修正动作

• 常见故障：同一篇草稿被保存多次。原因：通知重试或接收端重复消费事件。修正动作：以事件唯一标识或本地去重键建立唯一约束，并让保存草稿操作具备幂等性。
• 常见故障：收到通知却找不到任务。原因：提交任务时没有持久化 Gemini 任务标识，或环境之间混用了数据。修正动作：创建任务后立即保存 provider_job_id，并按测试与生产环境隔离记录。
• 常见故障：通知处理成功但正文为空。原因：把完成通知误认为最终内容，或结果尚未成功取回。修正动作：通知后单独读取最终结果，确认完成状态和正文非空后再保存草稿。
• 常见故障：外部请求可以直接触发发布。原因：接收地址缺少官方要求的来源验证，或发布状态与任务状态耦合。修正动作：先执行官方认证校验，并将发布权限限制在独立审核流程。
• 常见故障：任务失败后无人发现。原因：失败状态只写日志，没有进入后台待办。修正动作：为 failed 和未知任务建立告警或人工处理队列，并保留重试次数与最后错误。

发布前检查项

• 本地 task_id、Gemini 任务标识、文章草稿 ID 能相互对应。
• 完成通知已通过官方规定的认证或来源验证。
• 重复投递同一通知不会新增草稿版本，也不会重复发布。
• 已从最终任务结果取得正文，且正文长度、结构和必填字段符合后台规则。
• 生成内容进入审核状态，未因收到通知自动公开。
• 任务日志不含 API 密钥、认证材料或不应暴露的原始资料。
• 用测试任务演练过完成、失败、重复通知和未知任务四种情形。

完成这些检查后，Webhook 才真正替代了人工轮询：通知负责唤醒流程，任务表负责追踪，草稿审核负责守住发布边界。