Gemini Webhooks API

借助 Webhook，Gemini API 可以在异步操作或长时间运行的操作 (LRO) 完成时，向您的服务器推送实时通知。这样就不再需要轮询 API 以获取状态更新，从而减少延迟和开销。

以 Markdown 格式查看 查看 OpenAPI 规范

CreateWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks

创建新的 Webhook。

请求正文

请求正文中包含结构如下的数据：

name string  （可选）

可选。用户提供的 webhook 名称。

subscribed_events array (enum (string))  （必需）

必需。Webhook 订阅的事件。 可用的事件： - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

可能的值：

  • batch.succeeded

    批处理已成功完成。

  • batch.expired

    相应批次未在 48 小时内处理完毕。

  • batch.failed

    批量作业失败。

  • interaction.requires_action

    互动需要采取行动（例如，函数调用）。

  • interaction.completed

    互动已成功完成。

  • interaction.failed

    互动失败。

  • video.generated

    视频生成已完成。

uri 字符串  （必需）

必需。将向其发送网络钩子事件的 URI。

响应

如果成功，响应正文将包含结构如下的数据：

create_time string  （选填）

仅限输出。创建 Webhook 时的时间戳。

id string  （选填）

仅限输出。网络钩子的 ID。

name string  （可选）

可选。用户提供的 webhook 名称。

new_signing_secret string  （可选）

仅限输出。网络钩子的新签名密钥。仅在创建时填充。

signing_secrets array (SigningSecret)  （可选）

仅限输出。与相应 webhook 关联的签名密钥。

表示用于验证 webhook 载荷的签名密钥。

字段

expire_time string  （选填）

仅限输出。签名密钥的失效日期。

truncated_secret string  （选填）

仅限输出。签名密钥的截断版本。

state enum (string)  （选填）

仅限输出。Webhook 的状态。

可能的值：

  • enabled

    网络钩子已启用。

  • disabled

    用户已停用 webhook。

  • disabled_due_to_failed_deliveries

    由于传送失败，Webhook 已停用。

subscribed_events 数组（枚举 [string]）  （选填）

必需。Webhook 订阅的事件。 可用的事件： - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

可能的值：

  • batch.succeeded

    批处理已成功完成。

  • batch.expired

    相应批次未在 48 小时内处理完毕。

  • batch.failed

    批量作业失败。

  • interaction.requires_action

    互动需要采取行动（例如，函数调用）。

  • interaction.completed

    互动已成功完成。

  • interaction.failed

    互动失败。

  • video.generated

    视频生成已完成。

update_time string  （选填）

仅限输出。上次更新 Webhook 时的时间戳。

uri string  （选填）

必需。将向其发送网络钩子事件的 URI。

示例

示例响应

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

PingWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping

向 Webhook 发送 ping 事件。

路径 / 查询参数

id string  （必需）

必需。要 ping 的 webhook 的 ID。 格式：`{webhook_id}`

请求正文

请求正文中包含结构如下的数据：

响应

如果成功，则响应为空。

示例

RotateSigningSecret

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret

为 Webhook 生成新的签名密钥。

路径 / 查询参数

id string  （必需）

必需。要为其生成签名密钥的 webhook 的 ID。 格式：`{webhook_id}`

请求正文

请求正文中包含结构如下的数据：

revocation_behavior 枚举（字符串）  （可选）

可选。之前签名密钥的撤消行为。

可能的值：

  • revoke_previous_secrets_after_h24

    生成新的签名密钥，并在 24 小时后撤消所有旧密钥。迁移的默认且最安全的选项。

  • revoke_previous_secrets_immediately

    立即撤消所有之前的密钥。请谨慎使用，因为这可能会中断正在进行的通知。

响应

如果成功，响应正文将包含结构如下的数据：

secret string  （选填）

仅限输出。新生成的签名密钥。

示例

示例响应

{
  "secret": "string"
}

ListWebhooks

get https://generativelanguage.googleapis.com/v1beta/webhooks

列出所有 Webhook。

路径 / 查询参数

page_size integer  （可选）

可选。要返回的 Webhook 数量上限。服务返回的值可能小于此值。如果未指定，则最多返回 50 个 Webhook。 最大值为 1000。

page_token string  （可选）

可选。从之前的 `ListWebhooks` 调用中收到的页面令牌。 利用其进行后续页面检索。

响应

如果成功，响应正文将包含结构如下的数据：

next_page_token string  （可选）

可作为 `page_token` 发送并用于检索下一页的令牌。 如果省略此字段，则不存在后续页面。

网络钩子 数组（Webhook）  （可选）

Webhook。

示例

示例响应

{
  "next_page_token": "string",
  "webhooks": [
    {
      "create_time": "string",
      "id": "string",
      "name": "string",
      "new_signing_secret": "string",
      "signing_secrets": [
        {
          "expire_time": "string",
          "truncated_secret": "string"
        }
      ],
      "state": "enabled",
      "subscribed_events": [
        "batch.succeeded"
      ],
      "update_time": "string",
      "uri": "string"
    }
  ]
}

GetWebhook

get https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

获取特定的 Webhook。

路径 / 查询参数

id string  （必需）

必需。要检索的 webhook 的 ID。

响应

如果成功，响应正文将包含结构如下的数据：

create_time string  （选填）

仅限输出。创建 Webhook 时的时间戳。

id string  （选填）

仅限输出。网络钩子的 ID。

name string  （可选）

可选。用户提供的 webhook 名称。

new_signing_secret string  （可选）

仅限输出。网络钩子的新签名密钥。仅在创建时填充。

signing_secrets array (SigningSecret)  （可选）

仅限输出。与相应 webhook 关联的签名密钥。

表示用于验证 webhook 载荷的签名密钥。

字段

expire_time string  （选填）

仅限输出。签名密钥的失效日期。

truncated_secret string  （选填）

仅限输出。签名密钥的截断版本。

state enum (string)  （选填）

仅限输出。Webhook 的状态。

可能的值：

  • enabled

    网络钩子已启用。

  • disabled

    用户已停用 webhook。

  • disabled_due_to_failed_deliveries

    由于传送失败，Webhook 已停用。

subscribed_events 数组（枚举 [string]）  （选填）

必需。Webhook 订阅的事件。 可用的事件： - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

可能的值：

  • batch.succeeded

    批处理已成功完成。

  • batch.expired

    相应批次未在 48 小时内处理完毕。

  • batch.failed

    批量作业失败。

  • interaction.requires_action

    互动需要采取行动（例如，函数调用）。

  • interaction.completed

    互动已成功完成。

  • interaction.failed

    互动失败。

  • video.generated

    视频生成已完成。

update_time string  （选填）

仅限输出。上次更新 Webhook 时的时间戳。

uri string  （选填）

必需。将向其发送网络钩子事件的 URI。

示例

示例响应

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

UpdateWebhook

patch https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

更新现有 Webhook。

路径 / 查询参数

id string  （必需）

必需。要更新的 webhook 的 ID。

update_mask string  （选填）

可选。要更新的字段列表。

请求正文

请求正文中包含结构如下的数据：

name string  （可选）

可选。用户提供的 webhook 名称。

state enum (string)  （选填）

可选。Webhook 的状态。

可能的值：

  • enabled

    网络钩子已启用。

  • disabled

    用户已停用 webhook。

  • disabled_due_to_failed_deliveries

    由于传送失败，Webhook 已停用。

subscribed_events 数组（枚举 [string]）  （选填）

可选。Webhook 订阅的事件。 可用的事件： - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

可能的值：

  • batch.succeeded

    批处理已成功完成。

  • batch.expired

    相应批次未在 48 小时内处理完毕。

  • batch.failed

    批量作业失败。

  • interaction.requires_action

    互动需要采取行动（例如，函数调用）。

  • interaction.completed

    互动已成功完成。

  • interaction.failed

    互动失败。

  • video.generated

    视频生成已完成。

uri string  （选填）

可选。将向其发送网络钩子事件的 URI。

响应

如果成功，响应正文将包含结构如下的数据：

create_time string  （选填）

仅限输出。创建 Webhook 时的时间戳。

id string  （选填）

仅限输出。网络钩子的 ID。

name string  （可选）

可选。用户提供的 webhook 名称。

new_signing_secret string  （可选）

仅限输出。网络钩子的新签名密钥。仅在创建时填充。

signing_secrets array (SigningSecret)  （可选）

仅限输出。与相应 webhook 关联的签名密钥。

表示用于验证 webhook 载荷的签名密钥。

字段

expire_time string  （选填）

仅限输出。签名密钥的失效日期。

truncated_secret string  （选填）

仅限输出。签名密钥的截断版本。

state enum (string)  （选填）

仅限输出。Webhook 的状态。

可能的值：

  • enabled

    网络钩子已启用。

  • disabled

    用户已停用 webhook。

  • disabled_due_to_failed_deliveries

    由于传送失败，Webhook 已停用。

subscribed_events 数组（枚举 [string]）  （选填）

必需。Webhook 订阅的事件。 可用的事件： - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

可能的值：

  • batch.succeeded

    批处理已成功完成。

  • batch.expired

    相应批次未在 48 小时内处理完毕。

  • batch.failed

    批量作业失败。

  • interaction.requires_action

    互动需要采取行动（例如，函数调用）。

  • interaction.completed

    互动已成功完成。

  • interaction.failed

    互动失败。

  • video.generated

    视频生成已完成。

update_time string  （选填）

仅限输出。上次更新 Webhook 时的时间戳。

uri string  （选填）

必需。将向其发送网络钩子事件的 URI。

示例

示例响应

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

DeleteWebhook

delete https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

删除网络钩子。

路径 / 查询参数

id string  （必需）

必需。要删除的 webhook 的 ID。 格式：`{webhook_id}`

响应

如果成功，则响应为空。

示例

资源

网络钩子

一种网络钩子资源。

字段

create_time string  （选填）

仅限输出。创建 Webhook 时的时间戳。

id string  （选填）

仅限输出。网络钩子的 ID。

name string  （可选）

可选。用户提供的 webhook 名称。

new_signing_secret string  （可选）

仅限输出。网络钩子的新签名密钥。仅在创建时填充。

signing_secrets array (SigningSecret)  （可选）

仅限输出。与相应 webhook 关联的签名密钥。

表示用于验证 webhook 载荷的签名密钥。

字段

expire_time string  （选填）

仅限输出。签名密钥的失效日期。

truncated_secret string  （选填）

仅限输出。签名密钥的截断版本。

state enum (string)  （选填）

仅限输出。Webhook 的状态。

可能的值：

  • enabled

    网络钩子已启用。

  • disabled

    用户已停用 webhook。

  • disabled_due_to_failed_deliveries

    由于传送失败，Webhook 已停用。

subscribed_events 数组（枚举 [string]）  （选填）

必需。Webhook 订阅的事件。 可用的事件： - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

可能的值：

  • batch.succeeded

    批处理已成功完成。

  • batch.expired

    相应批次未在 48 小时内处理完毕。

  • batch.failed

    批量作业失败。

  • interaction.requires_action

    互动需要采取行动（例如，函数调用）。

  • interaction.completed

    互动已成功完成。

  • interaction.failed

    互动失败。

  • video.generated

    视频生成已完成。

update_time string  （选填）

仅限输出。上次更新 Webhook 时的时间戳。

uri string  （选填）

必需。将向其发送网络钩子事件的 URI。