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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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)

仅限输出。适用于相应维护的控制措施（可能不适用于应用了相应维护的每项资源）。
stats[]

object (Stats)

仅限输出。统计信息是 ResourceMaintenance 的一个字段，用于汇总统计信息。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 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)

Aggregates 是一个 <group, count> 对列表。例如，如果 group_by 为 "state"，则汇总列表中的一个可能元组为“SCHEDULED”：11，

汇总

JSON 表示法 
{
  "group": string,
  "count": string
}
字段
group

string

指定 group_by 的哪个特定值表示相应数量。例如，如果 group_by 为 "state"，则其对应的群组可以是 "SCHEDULED"。
count

string (int64 format)

群组的数量。

MaintenanceCategory

维护的类别。

枚举
MAINTENANCE_CATEGORY_UNSPECIFIED 未指定的类别。
INFRASTRUCTURE 基础设施维护事件是指 Google Cloud 对网络设备（例如 Google Cloud Interconnect）执行常规维护的时间。这些事件通常是提前安排的，我们会尽可能提供通知，以便用户针对基础设施维护事件进行规划并防止停机。基础架构维护事件相隔的时间不固定，但通常是一年几次。
SERVICE_UPDATE 更新可能包含与现有版本（包括补丁）向后兼容的 bug 修复、变更或新功能。部分 SP 允许用户使用维护期和/或拒绝维护功能来控制这些维护事件的安排。

控制

设置支持的控制类型。注释（如日志中所示）。

枚举
CONTROL_UNSPECIFIED 未指定的控制类型。
APPLY 应用控制。
MANAGE_POLICY 管理政策控制。
RESCHEDULE 重新安排控制。

工具注释

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌