本頁面由 Cloud Translation API 翻譯而成。

許可控制

簡介

本頁面說明如何使用 Service Control API 第 2 版，為整合服務基礎架構的代管服務進行准入控制。適用於想將服務與 Google Cloud 深度整合的服務生產者。

服務基礎架構是開發人員用來產生、管理、保護及使用 API 和服務的基礎平台。它採用簡單的通用服務使用模型：消費者使用生產者管理的服務。所有 Google API 和 Google Cloud API 都使用這個模型，因為這些 API 也是以服務基礎架構為基礎建構而成。

當用戶端存取服務時，通常需要對所有參與存取的實體進行狀態和政策檢查，包括消費者、服務、生產者、使用者、應用程式、網路和資源。在服務基礎架構中，這項程序稱為「准入控管」，包括驗證、授權、稽核、頻率限制等。

Service Control API v2

Service Control API 第 2 版提供簡單的 services.check 方法，可為所有與服務基礎架構整合的服務提供准入控制。這個方法可讓您在單一方法呼叫中執行下列操作：

檢查狀態
- 濫用狀態
- 帳單狀態
- 消費者狀態
- 服務狀態
- 啟用服務
驗證
- Google OAuth 存取權杖
- Google 服務帳戶簽署的 JWT
授權
- 身分與存取權管理 (IAM)
稽核
- Cloud 稽核記錄。稽核記錄與「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。

Attibute	說明	範例
`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 要求標頭。必要標題為「authorization」、「user-agent」、「origin」、「referer」。
`resource.name`	目標資源名稱。	"projects/123/topics/news-feed"

資源屬性

當用戶端存取服務時，存取作業可能會涉及服務內的一或多個資源，例如讀取物件或建立 VM 執行個體。這項服務可使用 Service Infrastructure 准入控制機制，對資源進行存取控制，並支援 IAM 和 Cloud 稽核記錄。如果您的服務不需要存取權控管，可以略過這個部分。

如要進行存取權控管，服務必須將資源屬性連同要求屬性傳遞至 services.check 方法。下表列出存取控制所需的資源屬性。

Attibute	說明	範例
`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。這類程式庫提供絕佳的可用性，並自動處理常見功能，例如驗證。詳情請參閱「用戶端程式庫說明」。