MCP Tools Reference: maintenance.googleapis.com

工具：summarize_maintenances

提供匯總統計資料，總結指定專案和位置的維護作業。

參數

  • parent (字串，必填)：資源維護作業的父項，格式為 projects/{project}/locations/{location}。
  • page_size (整數，選填)：每頁要傳送的資源維護作業數量上限。
  • page_token (字串，選用)：接收自前一個 SummarizeMaintenances 呼叫的頁面權杖。
  • filter (字串，選用)：按照 https://google.aip.dev/160 的規定篩選清單。
  • order_by (字串，選用)：按照 https://google.aip.dev/132 中指定的順序排列結果。

傳回值

這個方法會傳回 SummarizeMaintenancesResponse 物件，其中包含：

  • maintenances：維護摘要清單。
  • next_page_token：可做為後續要求中的 page_token 傳送的權杖，用於擷取下一頁結果。

注意事項

  • 如要查看所有區域的全球摘要，請使用「-」做為位置。

下列範例示範如何使用 curl 叫用 summarize_maintenances MCP 工具。

Curl 要求 
                  
curl --location 'https://maintenance.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "summarize_maintenances",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

SummarizeMaintenances 自訂方法的要求訊息。

SummarizeMaintenancesRequest

JSON 表示法 
{
  "parent": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string,
  "orderBy": string
}
欄位
parent

string

這是必要旗標，資源維護作業的父項，例如 projects/123/locations/*
pageSize

integer

每頁要傳送的資源維護作業數量上限。預設頁面大小為 20，上限為 1000。
pageToken

string

頁面符記：如果提供先前回應中的 next_page_token，這項要求會傳送後續頁面。
filter

string

按照 https://google.aip.dev/160 的規定篩選清單。支援的欄位包括：- maintenance.maintenanceName 範例：- maintenance.maintenanceName="eb3b709c-9ca1-5472-9fb6-800a3849eda1"
orderBy

string

按照 https://google.aip.dev/132 的規定排序結果。

輸出內容的結構定義

SummarizeMaintenances 自訂方法的要求訊息。

SummarizeMaintenancesResponse

JSON 表示法 
{
  "maintenances": [
    {
      object (MaintenanceSummary)
    }
  ],
  "nextPageToken": string,
  "unreachable": [
    string
  ]
}
欄位
maintenances[]

object (MaintenanceSummary)

產生的摘要。
nextPageToken

string

如果有的話，可將下一頁符記提供給後續的 SummarizeMaintenances 呼叫，列出下一頁。如果留空，表示沒有其他頁面。
unreachable[]

string

未排序的清單。無法連線的位置。

MaintenanceSummary

JSON 表示法 
{
  "maintenanceName": string,
  "title": string,
  "description": string,
  "category": enum (MaintenanceCategory),
  "maintenanceScheduledStartTime": string,
  "maintenanceScheduledEndTime": string,
  "maintenanceStartTime": string,
  "maintenanceEndTime": string,
  "userControllable": boolean,
  "controls": [
    {
      object (MaintenanceControl)
    }
  ],
  "stats": [
    {
      object (Stats)
    }
  ]
}
欄位
maintenanceName

string

僅供輸出。維護作業的名稱。
title

string

僅供輸出。維護作業的標題。
description

string

僅供輸出。維護作業的說明。
category

enum (MaintenanceCategory)

僅供輸出。維護事件的類別。
maintenanceScheduledStartTime

string (Timestamp format)

僅供輸出。維護作業的排定開始時間。維護作業將於 maintenanceScheduledStartTime 開始，並盡力在 maintenanceScheduledEndTime 前完成。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
maintenanceScheduledEndTime

string (Timestamp format)

僅供輸出。預估 (盡力而為，不保證) 排定維護作業的結束時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
maintenanceStartTime

string (Timestamp format)

僅供輸出。維護作業的實際開始日期。只有在狀態變更為 RUNNING 後，才會顯示這個欄位。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
maintenanceEndTime

string (Timestamp format)

僅供輸出。維護作業實際完成的日期。只有在狀態變更為 SUCCEEDED 後，才會顯示這個欄位。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
userControllable

boolean

僅供輸出。指出使用者是否可控管該維護作業，包括在維護政策排定維護作業前主動控管，或在排定作業後被動控管 (請參閱「controls」欄位)。
controls[]

object (MaintenanceControl)

僅供輸出。可用的維護作業控制選項 (可能不適用於維護作業套用的所有資源)。
stats[]

object (Stats)

僅供輸出。Stats 是 ResourceMaintenance 的欄位，用於匯總統計資料。

時間戳記

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

代表自 Unix 紀元 1970-01-01T00:00:00Z 起算的世界標準時間秒數。必須介於 -62135596800 和 253402300799 之間 (含)，對應至 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Z。
nanos

integer

以奈秒為單位的非負秒數小數。這個欄位是時間長度的奈秒部分，並非秒數的替代值。如果秒數值為負數，且包含小數，奈秒值仍須為非負數，且會往前計算時間。必須介於 0 至 999,999,999 之間 (含)。

MaintenanceControl

JSON 表示法 
{
  "control": enum (Control),
  "isCustom": boolean,
  "documentation": string
}
欄位
control

enum (Control)

資源維護的控制權。
isCustom

boolean

指出控制項是否僅適用於 Service Producer API (不適用於 Unified Maintenance)。
documentation

string

服務生產者說明文件的連結，內容與維護控管有關。只有在 isCustom 為 true 時提供。

統計資料

JSON 表示法 
{
  "groupBy": string,
  "aggregates": [
    {
      object (Aggregate)
    }
  ]
}
欄位
groupBy

string

groupBy 會指定匯總類型。例如，group_by 可能為 "state"
aggregates[]

object (Aggregate)

匯總資料是 <群組, 數量> 配對清單。舉例來說，如果 group_by 是 "state"，則匯總清單中可能的元組可以是「SCHEDULED」：11，

匯總

JSON 表示法 
{
  "group": string,
  "count": string
}
欄位
group

string

指定 count 代表的 group_by 特定值。舉例來說，如果 group_by 是 "state"，對應的群組可以是 "SCHEDULED"。
count

string (int64 format)

群組數量。

MaintenanceCategory

維護作業類別。

列舉
MAINTENANCE_CATEGORY_UNSPECIFIED 未指定類別。
INFRASTRUCTURE 基礎架構維護事件是指 Google Cloud 對網路設備 (例如 Google Cloud Interconnect) 執行的定期維護作業。這類事件通常會事先排定時間，並盡可能提供通知，方便使用者規劃基礎架構維護事件，避免發生停機情形。基礎架構維護事件沒有一定的發生頻率，但通常每年會發生數次。
SERVICE_UPDATE 更新內容可能包括修正錯誤、變更或新功能，且與現有版本 (包括修補程式) 回溯相容。部分 SP 允許使用者透過維護期間和/或拒絕維護功能，控管這些維護事件的排程。

控制

設定支援的控管類型。註解 (如記錄檔)。

列舉
CONTROL_UNSPECIFIED 未指定的控制項。
APPLY 套用控制項。
MANAGE_POLICY 管理政策控制項。
RESCHEDULE 重新安排控制項。

工具註解

破壞性提示：❌ | 等冪提示：✅ | 唯讀提示：✅ | 開放世界提示：❌