企业官网建设流程全解析

• 示例工程

本文是 python-docs-samples 仓库中 Cloud Monitoring 目录下的 API Client 样例指南，核心围绕 monitoring/api/v3/api-client/README.rst 展开。Cloud Monitoring 用于采集并分析来自 Google Cloud、AWS、托管探针、应用埋点以及 Cassandra、Nginx、Apache、Elasticsearch 等常见组件的指标、事件与元数据，并通过仪表盘、图表和告警生成洞察。读完本文，你将掌握如何基于 Google API 客户端库（google-api-python-client）构建 Cloud Monitoring API V3 客户端，完成受监控资源描述符、指标描述符与时间序列三类数据的查询，并理解自定义指标读写的基本思路。

一、样例概览：README 与仓库结构

本目录的 README（由 README.rst.in 自动生成）登记了两个核心样例：

• List resources（list_resources.py）：检索 Cloud Monitoring API V3 数据，展示受监控资源、指标与时间序列的列举方式；
• Custom metrics（custom_metric.py）：演示连接 Monitoring API 写入自定义指标并读回，示例基于一个假设的 GAUGE 测量值。

需要说明的是：当前仓库快照中list_resources.py及其测试完整存在，而custom_metric.py已在目录中移除，其用法说明仍保留在 README 中（README.rst 第 97-131 行），本文据此还原其设计意图。目录还包含集成测试 list_resources_test.py 与依赖清单 requirements.txt、requirements-test.txt。

二、运行环境与前置准备

2.1 认证配置

本样例要求应用具备可用的凭据。官方推荐的方式是通过 Application Default Credentials（ADC）完成认证：为应用设置服务账号或用户凭据后，Google API 客户端库会自动从环境变量、gcloud 配置等位置加载凭据。集成测试的注释也印证了这一点——list_resources_test.py 要求GOOGLE_APPLICATION_CREDENTIALS指向一个已启用 Monitoring API 的项目的服务账号（见该文件第 17-24 行），测试运行的项目 ID 通过GOOGLE_CLOUD_PROJECT环境变量读取。

2.2 安装依赖

1. 克隆 python-docs-samples 仓库并进入样例目录：

   git clone https://gitcode.com/GitHub_Trending/py/python-docs-samples.git cd monitoring/api/v3/api-client

2. 创建虚拟环境并激活（README 注明样例兼容 Python 2.7 与 3.4+，实际当前实现使用 Python 3 特性，如带时区的datetime，建议使用 Python 3.8+）：

   virtualenv env source env/bin/activate

3. 安装运行依赖：

   pip install -r requirements.txt

requirements.txt 当前锁定三个关键包：

若需运行测试，另安装 requirements-test.txt 中的pytest、flaky（以及低版本 Python 下的backoff）。

三、List resources 样例深度解析

3.1 命令行参数

运行方式与参数在 README.rst 第 73-93 行给出：

python list_resources.py --project_id=<YOUR-PROJECT-ID>

• -h, --help：显示帮助信息；
• --project_id PROJECT_ID：必填，指定要访问的 Google Cloud 项目 ID。

参数解析实现在 list_resources.py 第 117-125 行：使用argparse并声明required=True，缺少项目 ID 时程序会直接报错退出。

3.2 客户端构建与项目资源定位

入口函数main(project_id)（第 106-114 行）完成了关键初始化：

client = googleapiclient.discovery.build("monitoring", "v3") project_resource = "projects/{}".format(project_id)

discovery.build("monitoring", "v3")基于 Discovery 文档动态生成 REST 客户端，无需手动编写 HTTP 调用代码。随后将项目 ID 组装成 API 资源名projects/<project_id>，作为后续所有 list 请求的name参数。

3.3 三类查询：受监控资源、指标描述符、时间序列

样例依次演示了三个projects.*下的 list 方法：

（1）受监控资源描述符——list_monitored_resource_descriptors（第 59-71 行）

client.projects().monitoredResourceDescriptors().list(name=project_resource)

该方法返回该 API 中所有可被监控的资源类型列表（如 GCE 实例、Pub/Sub 主题等），帮助你了解项目下存在哪些监控维度，响应通过pprint.pformat格式化输出。

（2）指标描述符——list_metric_descriptors（第 74-84 行）

client.projects().metricDescriptors().list( name=project_resource, filter='metric.type="{}"'.format(metric), )

与全量列举不同，这里使用filter精确过滤出指定的指标类型。样例默认查询的指标为：

compute.googleapis.com/instance/cpu/usage_time

即 Compute Engine 实例的 CPU 使用时间，这是 GCP 内置的指标描述符之一。返回值会说明该指标的度量类型（如 DELTA/GAUGE/CUMULATIVE）、单位与标签结构。

（3）时间序列——list_timeseries（第 87-103 行）

client.projects().timeSeries().list( name=project_resource, filter='metric.type="{}"'.format(metric), pageSize=3, interval_startTime=get_start_time(), interval_endTime=get_end_time(), )

这是三个查询中最贴近业务的一个：在指定时间窗口内读取该指标的实际采样点。注意这里设置了pageSize=3以限制返回条数，并通过interval_startTime/interval_endTime划定查询区间。

时间窗口的计算逻辑（第 34-56 行）值得单独说明：

• get_start_time()返回「当前 UTC 时间往前 1 小时 5 分钟」的时刻，即窗口起点为 1 小时前再提前 5 分钟；
• get_end_time()返回「当前 UTC 时间往前 1 小时」的时刻，即窗口终点为 1 小时前。

两者合起来构成一个跨越 5 分钟（且完全落在过去）的查询窗口，这样设计是为了「读回此前写入的自定义指标值」，确保窗口覆盖写入发生的时间段。两个函数都基于datetime.datetime.now(tz=datetime.timezone.utc)生成带 UTC 时区的 ISO 8601 字符串，避免时区歧义。

3.4 运行输出示例

执行python list_resources.py --project_id=<YOUR-PROJECT-ID>后，程序依次打印三段响应：

• list_monitored_resource_descriptors response: ...：受监控资源类型清单；
• list_metric_descriptors response: ...：compute.googleapis.com/instance/cpu/usage_time的指标描述符；
• list_timeseries response: ...：该指标在最近 5 分钟窗口内至多 3 条时间序列采样点。

输出均为 JSON 结构，可直接在终端中检查数据结构或进一步接入其他处理逻辑。

3.5 源码级验证：集成测试如何校验结果

list_resources_test.py 对上述三个查询逐一做了集成测试（均标记@pytest.mark.flaky，容忍偶发网络波动）：

测试通过capsys捕获print输出，并用正则校验关键字段，从侧面印证了 list_resources.py 的输出格式与 API 响应结构。运行方式：

export GOOGLE_CLOUD_PROJECT=<your-project-id> export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json pytest list_resources_test.py

四、Custom metrics 样例：写入并读回自定义指标

根据 README.rst 第 97-131 行的记录，第二个样例custom_metric.py的设计目标是：

演示连接 Google Monitoring API 写入自定义指标并读回，该示例基于一个假设的 GAUGE 测量值创建自定义指标。

其命令行接口与list_resources.py完全一致：

python custom_metric.py --project_id=<YOUR-PROJECT-ID>

• --project_id PROJECT_ID：必填，指定要访问的项目 ID。

从 README 的「简单命令行程序」「基于假设的 GAUGE 测量」描述可以推断（结合 Monitoring API V3 的标准流程），该样例的核心步骤包括：

1. 创建/确认自定义指标描述符：通过projects.metricDescriptors.create定义一个形如custom.googleapis.com/<metric-name>的指标描述符，指定其metricKind为GAUGE（瞬时测量值，而非累计计数）；
2. 写入时间序列点：通过projects.timeSeries.create将带时间戳的采样点写入该指标，GAUGE 指标每次写入代表当前时刻的测量快照；
3. 读回验证：利用list_timeseries在时间窗口内查询刚写入的值，与list_resources.py中get_start_time()/get_end_time()的 5 分钟回溯窗口设计相呼应——这正是 list_resources.py 中时间窗口特意「再提前 5 分钟」的原因，确保写入点落在可查询区间内。

需要提醒的是：当前仓库快照中已不包含custom_metric.py源文件，上述流程为基于 README 描述与 API 语义的还原。若你的项目需要完整可运行的自定义指标样例，可参考同仓库 monitoring/snippets/v3/cloud-client/snippets.py 与 quickstart.py 中关于自定义指标的实现，二者位于同一 API 版本目录下，接口语义一致。

五、常见问题与排查建议

• 认证失败（401/403）：确认GOOGLE_APPLICATION_CREDENTIALS已指向启用了 Monitoring API 的项目服务账号，且项目已开通 Monitoring API；
• 输出为空的时间序列：list_timeseries的查询窗口是「1 小时前到 1 小时前 5 分钟」，只有该窗口内存在采样点才会返回数据。对于刚写入的自定义指标，请确认写入时间落在窗口内；
• 指标类型过滤写法：filter使用 Monitoring 过滤语法metric.type="..."，引号内为完整指标类型名，拼写错误会返回空结果而非报错；
• 依赖版本兼容：google-api-python-client锁定的 2.131.0 与google-auth-httplib2搭配是官方验证过的组合，建议保持版本一致以避免传输层凭据桥接问题。

六、总结

本文围绕 monitoring/api/v3/api-client/README.rst 完整还原了 Cloud Monitoring API V3 客户端的两个核心场景：

• List resources：通过 list_resources.py 展示monitoredResourceDescriptors、metricDescriptors、timeSeries三个 list 方法的用法，含过滤语法、分页与时间窗口设计，并有 list_resources_test.py 提供可验证的集成测试；
• Custom metrics：依据 README 记录还原了「创建 GAUGE 自定义指标 → 写入 → 窗口读回」的闭环思路。

这两类操作构成了 Cloud Monitoring 数据接入与查询的最小闭环：前者是理解项目监控数据结构的起点，后者是业务自定义埋点的基础。掌握googleapiclient.discovery.build("monitoring", "v3")构建客户端、projects/{id}资源定位与三类 list 请求的调用模式后，你就能在此基础上扩展出告警策略管理、仪表盘查询等更复杂的监控能力。

• 示例工程