简介
本页描述如何使用 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.check 方法，该方法为与 Service Infrastructure 集成的所有服务提供准入控制。此方法使您可以在单个方法调用中执行以下操作：
- 状态检查
- 滥用状态
- 结算状态
- 使用者状态
- 服务状态
- 服务启用
- 身份验证
- Google OAuth 访问令牌
- Google 服务账号已签署的 JWT
- 授权
- 审核
- Cloud Audit Logs。 审核日志与服务“externalaudit.googleapis.com”相关联。
当服务调用 Service Control API 时，生产者也是 Service Control API 的使用者。因此，services.check 方法还对 Service Control API 的调用执行准入控制。
为了使用调用 Service Control API 的服务，必须在生产者项目上启用 Service Control API，并对该服务具有适当的权限。如需了解详情，请参阅 Cloud API 使用入门和 Service Control 访问权限控制。
请求特性
当客户端访问服务时，该服务需要将访问抽象为一个或多个 API 请求，这些请求可通过准入控制进行检查。在大多数情况下，此类访问确实是真实的 API 请求。在其他情况下，访问可能是复杂的数据导入作业或 SQL 查询，并且服务需要根据一组虚拟 API 请求对访问进行建模，并对每个请求执行准入控制。
如要使用 Service Control API 执行准入控制，服务需要使用所需的请求特性调用 services.check 方法。下表列出了准入控制所需的特性。如需了解完整的规范，请参阅 AttributeContext。
| 特性 | 说明 | 示例 |
|---|---|---|
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” |
request.headers |
HTTP 请求标头。所需的标头是“授权”、“用户代理”、“来源”、“引用来源”。 | |
resource.name |
目标资源名称。 | “projects/123/topics/news-feed” |
资源特性
当客户端访问服务时，访问可能涉及服务内部的一个或多个资源，例如读取对象或创建虚拟机实例。该服务可以使用 Service Infrastructure 准入控制来对资源进行访问控制，IAM 和 Cloud Audit Logs支持该服务。如果您的服务不需要访问控制，则可以跳过此部分。
对于访问控制，服务需要将资源特性以及请求特性一起传递给 services.check 方法。下表显示了访问控制所需的资源特性。
| 特性 | 说明 | 示例 |
|---|---|---|
name |
资源名称。 | “projects/123/locations/global/instances/instance-1” |
type |
资源类型。格式为“{service}/{Kind}”。 | “endpointsapis.appspot.com/Instance” |
permission |
资源权限。格式为“{service}/{kinds}.{verb}”。 | “endpointsapis.appspot.com/instances.get” |
为了提高性能和效率，您可使用 services.check 方法在一个调用中检查单个资源的多个权限。
执行准入控制
将服务配置部署到 Service Management API 之后，并且您的服务已准备就绪，可以处理来自客户端的请求，则可以开始为已部署的服务调用 services.check。每当您的服务收到请求时，您应该调用 services.check 执行准入控制。
如要快速尝试使用准入控制，可以使用 gcurl 命令调用 services.check 方法。如需了解初始设置步骤，请参阅 Service Control API 使用入门。
以下示例说明如何使用 gcurl 命令通过 HTTP 调用 services.check。
gcurl -d '{
"service_config_id": "latest",
"attributes": {
"origin": {
"ip": "1.2.3.4"
},
"api": {
"service": "endpointsapis.appspot.com",
"operation": "google.example.hello.v1.HelloService.GetHello",
"version": "v1",
"protocol": "https"
}
},
"request": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"time": "2019-07-31T05:20:00Z",
"scheme": "https",
"host": "endpointsapis.appspot.com"
"headers": {
"authorization": "Bearer xxx",
"user-agent": "curl/1.0"
}
},
"resources": [
]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}
services.check 方法的响应指示准入控制是否已通过。如果通过，则响应应该为空。如果失败，则响应中的 status 包含服务应返回给客户端的错误信息。该服务通常需要将错误信息转换为其自己的格式。该服务还可以将信息用于日志记录和监控目的。
对于生产服务，您应该使用 Google 提供的客户端库之一来调用 Service Control API。此类库提供了很高的可用性，并自动处理了常见功能，例如身份验证。如需了解详情，请参阅客户端库说明。