简介
本页面介绍了如何使用 Service Control API v2 对与 Service Infrastructure 集成的托管式服务进行遥测报告。适用于想要将其服务与 Google Cloud 深度集成的服务提供商。
Service Infrastructure 是一个基础平台，可供开发者生成、管理、保护和使用 API 和服务。它使用一个简单的通用性服务使用模型：使用者使用由生产者管理的服务。所有 Google API 和 Google Cloud API都使用此模型，因为它们也是基于 Service Infrastructure 构建的。
当使用方访问服务时，服务会向平台报告相关遥测数据，因此使用方和提供方都可以观察该访问。使用 Service Infrastructure，此过程被称为遥测报告，其中包括分析、审核、结算、日志记录和监控。
Service Control API v2
Service Control API v2 提供了一种简单的 services.report 方法，该方法为与 Service Infrastructure 集成的所有服务提供遥测报告。此方法使您可以在单个方法调用中执行以下操作：
- 分析
- 审核
- 结算
- 日志记录
- 监控
当服务向 Service Control API 报告遥测数据时，数据会被分发给使用方和/或提供方，具体取决于服务配置。如需详细了解如何配置遥测，请参阅 google.api.Service 的日志记录和监控部分。
为了使用调用 Service Control API 的服务，生产者必须在生产者项目上启用 Service Control API，而调用者必须对该服务具有适当的权限。如需了解详情，请参阅 Cloud API 使用入门和 Service Control API 访问权限控制。
请求特性
当客户端访问服务时，该服务需要根据一组 API 请求为访问建模，并使用 AttributeContext 描述每个请求。
要使用 Service Control API 报告 API 指标，服务需要使用下列特性针对每个请求调用 services.report 方法。Service Control API 将生成 API 指标并将其发送到 Cloud Monitoring。
| 属性 | 说明 | 示例 |
|---|---|---|
origin.ip |
调用方的 IP 地址。 | "1.2.3.4" |
api.service |
API 服务名称。 | “endpointsapis.appspot.com” |
api.operation |
API 方法名称。 | “google.example.hello.v1.HelloService.GetHello” |
api.version |
API 版本字符串。 | “v1” |
api.protocol |
API 协议名称。 | “https” |
request.id |
唯一的请求 ID。 | “123e4567-e89b-12d3-a456-426655440000” |
request.time |
请求时间戳。 | “2019-07-31T05:20:00Z” |
request.method |
HTTP 方法名称。 | “POST” |
request.scheme |
网址方案。 | “https” |
request.host |
HTTP 主机头。 | “endpointsapis.appspot.com” |
request.path |
网址路径。 | “/v1/hello” |
response.code |
响应状态代码。 | 200 |
response.size |
响应大小（以字节为单位）。 | 100 |
response.time |
响应时间戳。 | "2019-07-31T05:20:02Z" |
response.backend_latency |
后端延迟时间。 | “0.007 秒” |
执行遥测报告
将服务配置部署到 Service Management API 之后，并且您的服务已准备就绪，可以处理来自客户端的请求，则可以开始为已部署的服务调用 services.report。您的服务收到请求后，您应该调用 services.report 执行遥测报告。
如需快速试验遥测报告，您可以使用 gcurl 命令调用 services.report 方法。如需了解初始设置步骤，请参阅 Service Control API 使用入门。
以下示例说明如何使用 gcurl 命令通过 HTTP 调用 services.report。
gcurl -d '{
"service_config_id": "latest",
"operations": [{
"origin": {
"ip": "1.2.3.4"
},
"api": {
"service": "endpointsapis.appspot.com",
"operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
"version": "v1",
"protocol": "https"
},
"request": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"size": 50,
"time": "2019-07-31T05:20:00Z",
},
"response": {
"size": 100,
"code": 200,
"time": "2019-07-31T05:20:02Z",
"backend_latency": "0.007s"
},
"destination": {
"region_code": "us-central1"
}
"resource": {
"name": "projects/123/locations/us-central1/workspaces/default"
}
}]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report
如果成功，来自 services.report 方法的响应应为空。如果失败，API 错误应包含详细的错误信息。如需详细了解错误处理，请参阅 API 设计指南 > 错误。
对于生产服务，您应该使用 Google 提供的客户端库之一来调用 Service Control API。此类库提供了很高的可用性，并自动处理了常见功能，例如身份验证。如需了解详情，请参阅客户端库说明。