MCP Tools Reference: maintenance.googleapis.com

工具：list_resource_maintenances

列出指定專案和位置的資源維護作業。

參數

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

傳回值

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

  • resource_maintenances：符合要求條件的資源維護作業清單。
  • next_page_token：可做為後續要求中的 page_token 傳送的權杖，用於擷取下一頁結果。

注意事項

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

下列範例示範如何使用 curl 叫用 list_resource_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": "list_resource_maintenances",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

ListResourceMaintenances 方法的要求結構。

ListResourceMaintenancesRequest

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

string

這是必要旗標，資源維護作業的父項。
pageSize

integer

每頁要傳送的資源維護作業數量上限。
pageToken

string

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

string

按照 https://google.aip.dev/160 的規定篩選清單。
orderBy

string

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

輸出內容的結構定義

ListResourceMaintenances 方法的回應結構。

ListResourceMaintenancesResponse

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

object (ResourceMaintenance)

產生的資源維護作業。
nextPageToken

string

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

string

無法連線的位置。

ResourceMaintenance

JSON 表示法 
{
  "name": string,
  "resource": {
    object (Resource)
  },
  "maintenance": {
    object (Maintenance)
  },
  "state": enum (State),
  "createTime": string,
  "updateTime": string,
  "maintenanceStartTime": string,
  "maintenanceEndTime": string,
  "maintenanceCancelTime": string,
  "maintenanceScheduledStartTime": string,
  "maintenanceScheduledEndTime": string,
  "userControllable": boolean,
  "controls": [
    {
      object (MaintenanceControl)
    }
  ],
  "labels": {
    string: string,
    ...
  },
  "annotations": {
    string: string,
    ...
  },
  "uid": string,
  "etag": string
}
欄位
name

string

ID。resource_maintenance 資源的名稱。格式："projects/{project}/locations/{location}/resourceMaintenance/{resource-maintenance-id}"
resource

object (Resource)

僅供輸出。資源維護的資源規格。
maintenance

object (Maintenance)

僅供輸出。維護作業詳細資料。
state

enum (State)

僅供輸出。資源維護作業的狀態。
createTime

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"。
updateTime

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)

僅供輸出。資源維護作業的開始時間。

使用 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)

僅供輸出。資源維護作業完成的時間。

使用 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"。
maintenanceCancelTime

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"。
maintenanceScheduledStartTime

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"。
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"。
userControllable

boolean

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

object (MaintenanceControl)

僅供輸出。維護作業的控制選項。
labels

map (key: string, value: string)

選用。資源上的標籤，可用於分類，類似於 Kubernetes 資源標籤。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
annotations

map (key: string, value: string)

選用。註解是與資源一起儲存的非結構化鍵/值對應，可由外部工具設定，用於儲存及擷取任意中繼資料。這些屬性無法查詢，修改物件時應保留這些屬性。

詳情請參閱：https://kubernetes.io/docs/user-guide/annotations

包含 "key": value 組合清單的物件，例如 { "name": "wrench", "mass": "1.3kg", "count": "3" }。
uid

string

僅供輸出。資源專屬識別碼。在服務範圍內，這項資源適用的時間和空間中，UID 是獨一無二的。UID 通常是由伺服器在成功建立資源時產生，且不可變更。資源名稱會重複使用，因此您可以使用 UID 明確識別資源。這應為 UUID4。
etag

string

僅供輸出。能明確識別版本或產生資源的不透明值。可用來確認用戶端和伺服器同意寫入資源的順序。

資源

JSON 表示法 
{
  "resourceName": string,
  "location": string,
  "type": string
}
欄位
resourceName

string

僅供輸出。名稱是指受維護作業影響的消費者資源。如要查看可用的值，請前往：https://cloud.google.com/asset-inventory/docs/asset-names
location

string

僅供輸出。資源位置。格式：us-central1
type

string

僅供輸出。資源類型。如要查看可用值，請前往 https://cloud.google.com/asset-inventory/docs/asset-types#supported_resource_types。請注意，並非所有資源類型都會回報維護作業。

維護

JSON 表示法 
{
  "maintenanceName": string,
  "title": string,
  "description": string,
  "category": enum (MaintenanceCategory)
}
欄位
maintenanceName

string

維護作業是相應維護資源的名稱，遵循標準命名配置："{maintenance-id}"
title

string

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

string

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

enum (MaintenanceCategory)

僅供輸出。維護作業的類別。

時間戳記

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 時提供。

LabelsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string

AnnotationsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string

MaintenanceCategory

維護作業類別。

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

狀態

狀態是資源維護作業的狀態。

列舉
STATE_UNSPECIFIED 未指定狀態。
SCHEDULED 排定在特定時間範圍內發布。如果維護作業會造成中斷，則應遵守維護政策，也就是可用的時間範圍、排除時段和通知期限。
RUNNING 維護作業仍在進行中。
CANCELLED 不再規劃，通常是已進行其他維護作業 (例如升級至新版)，或是使用者略過維護作業。
SUCCEEDED 已順利完成。

控制

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

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

工具註解

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