Gemini Webhooks API

當非同步或長時間執行的作業 (LRO) 完成時，Gemini API 可透過 Webhook 將即時通知推送至伺服器。這樣就不必輪詢 API 來取得狀態更新，可減少延遲和額外負荷。

以 Markdown 格式查看 查看 OpenAPI 規格

CreateWebhook

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

建立新的 Webhook。

要求主體

要求主體會包含結構如下的資料：

名稱 字串  (選用)

(選用步驟) 使用者提供的 Webhook 名稱。

subscribed_events 陣列 (列舉 (字串))  (必要)

必填。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  (必要)

必填。Webhook 事件的傳送 URI。

回應

如果成功，回應主體會含有以下結構的資料：

create_time string  (選用)

僅供輸出。Webhook 的建立時間戳記。

id string  (選填)

僅供輸出。網路鉤子的 ID。

名稱 字串  (選用)

(選用步驟) 使用者提供的 Webhook 名稱。

new_signing_secret 字串  (選用)

僅供輸出。Webhook 的新簽署密鑰。只會在建立時填入。

signing_secrets array (SigningSecret)  (optional)

僅供輸出。與這個 Webhook 相關聯的簽署密鑰。

代表用於驗證 Webhook 酬載的簽署密鑰。

欄位

expire_time string  (選用)

僅供輸出。簽署密鑰的到期日。

truncated_secret 字串  (選用)

僅供輸出。簽署密鑰的截斷版本。

state 列舉 (字串)  (選填)

僅供輸出。Webhook 的狀態。

可能的值：

  • enabled

    Webhook 已啟用。

  • disabled

    使用者已停用 Webhook。

  • disabled_due_to_failed_deliveries

    由於傳送失敗，Webhook 已停用。

subscribed_events 陣列 (列舉 (字串))  (選用)

必填。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  (選用)

僅供輸出。上次更新網路鉤子的時間戳記。

uri string  (選填)

必填。Webhook 事件的傳送 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

將 Ping 事件傳送至 Webhook。

路徑 / 查詢參數

id 字串  (必要)

必填。要 Ping 的 Webhook ID。 格式：`{webhook_id}`

要求主體

要求主體會包含結構如下的資料：

回應

如果成功，回應會留白。

範例

RotateSigningSecret

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

為 Webhook 產生新的簽署密鑰。

路徑 / 查詢參數

id 字串  (必要)

必填。要產生簽署密鑰的 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 整數  (選用)

(選用步驟) 要傳回的 Webhook 數量上限。服務傳回的產品數量可能會少於這個值。如未指定，最多將傳回 50 個 Webhook。最大值為 1000。

page_token string  (選用)

(選用步驟) 接收自先前 `ListWebhooks` 呼叫的網頁權杖。 提供此項目即可擷取後續網頁。

回應

如果成功，回應主體會含有以下結構的資料：

next_page_token string  (選用)

可做為 `page_token` 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

webhooks 陣列 (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 字串  (必要)

必填。要擷取的 Webhook ID。

回應

如果成功，回應主體會含有以下結構的資料：

create_time string  (選用)

僅供輸出。Webhook 的建立時間戳記。

id string  (選填)

僅供輸出。網路鉤子的 ID。

名稱 字串  (選用)

(選用步驟) 使用者提供的 Webhook 名稱。

new_signing_secret 字串  (選用)

僅供輸出。Webhook 的新簽署密鑰。只會在建立時填入。

signing_secrets array (SigningSecret)  (optional)

僅供輸出。與這個 Webhook 相關聯的簽署密鑰。

代表用於驗證 Webhook 酬載的簽署密鑰。

欄位

expire_time string  (選用)

僅供輸出。簽署密鑰的到期日。

truncated_secret 字串  (選用)

僅供輸出。簽署密鑰的截斷版本。

state 列舉 (字串)  (選填)

僅供輸出。Webhook 的狀態。

可能的值：

  • enabled

    Webhook 已啟用。

  • disabled

    使用者已停用 Webhook。

  • disabled_due_to_failed_deliveries

    由於傳送失敗，Webhook 已停用。

subscribed_events 陣列 (列舉 (字串))  (選用)

必填。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  (選用)

僅供輸出。上次更新網路鉤子的時間戳記。

uri string  (選填)

必填。Webhook 事件的傳送 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 字串  (必要)

必填。要更新的 Webhook ID。

update_mask 字串  (選用)

(選用步驟) 要更新的欄位清單。

要求主體

要求主體會包含結構如下的資料：

名稱 字串  (選用)

(選用步驟) 使用者提供的 Webhook 名稱。

state 列舉 (字串)  (選填)

(選用步驟) Webhook 的狀態。

可能的值：

  • enabled

    Webhook 已啟用。

  • disabled

    使用者已停用 Webhook。

  • disabled_due_to_failed_deliveries

    由於傳送失敗，Webhook 已停用。

subscribed_events 陣列 (列舉 (字串))  (選用)

(選用步驟) 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  (選填)

(選用步驟) Webhook 事件的傳送 URI。

回應

如果成功，回應主體會含有以下結構的資料：

create_time string  (選用)

僅供輸出。Webhook 的建立時間戳記。

id string  (選填)

僅供輸出。網路鉤子的 ID。

名稱 字串  (選用)

(選用步驟) 使用者提供的 Webhook 名稱。

new_signing_secret 字串  (選用)

僅供輸出。Webhook 的新簽署密鑰。只會在建立時填入。

signing_secrets array (SigningSecret)  (optional)

僅供輸出。與這個 Webhook 相關聯的簽署密鑰。

代表用於驗證 Webhook 酬載的簽署密鑰。

欄位

expire_time string  (選用)

僅供輸出。簽署密鑰的到期日。

truncated_secret 字串  (選用)

僅供輸出。簽署密鑰的截斷版本。

state 列舉 (字串)  (選填)

僅供輸出。Webhook 的狀態。

可能的值：

  • enabled

    Webhook 已啟用。

  • disabled

    使用者已停用 Webhook。

  • disabled_due_to_failed_deliveries

    由於傳送失敗，Webhook 已停用。

subscribed_events 陣列 (列舉 (字串))  (選用)

必填。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  (選用)

僅供輸出。上次更新網路鉤子的時間戳記。

uri string  (選填)

必填。Webhook 事件的傳送 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}

刪除 Webhook。

路徑 / 查詢參數

id 字串  (必要)

必填。要刪除的 Webhook ID。 格式：`{webhook_id}`

回應

如果成功，回應會留白。

範例

資源

Webhook

Webhook 資源。

欄位

create_time string  (選用)

僅供輸出。Webhook 的建立時間戳記。

id string  (選填)

僅供輸出。網路鉤子的 ID。

名稱 字串  (選用)

(選用步驟) 使用者提供的 Webhook 名稱。

new_signing_secret 字串  (選用)

僅供輸出。Webhook 的新簽署密鑰。只會在建立時填入。

signing_secrets array (SigningSecret)  (optional)

僅供輸出。與這個 Webhook 相關聯的簽署密鑰。

代表用於驗證 Webhook 酬載的簽署密鑰。

欄位

expire_time string  (選用)

僅供輸出。簽署密鑰的到期日。

truncated_secret 字串  (選用)

僅供輸出。簽署密鑰的截斷版本。

state 列舉 (字串)  (選填)

僅供輸出。Webhook 的狀態。

可能的值：

  • enabled

    Webhook 已啟用。

  • disabled

    使用者已停用 Webhook。

  • disabled_due_to_failed_deliveries

    由於傳送失敗，Webhook 已停用。

subscribed_events 陣列 (列舉 (字串))  (選用)

必填。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  (選用)

僅供輸出。上次更新網路鉤子的時間戳記。

uri string  (選填)

必填。Webhook 事件的傳送 URI。