遙測報告

簡介

本頁面說明如何使用 Service Control API 第 2 版，為整合服務基礎架構的代管服務回報遙測資料。適用於想將服務與 Google Cloud 深度整合的服務生產者。

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

當消費者存取服務時，服務會向平台回報相關遙測資料，因此消費者和生產者都能觀察存取情形。在服務基礎架構中，這個程序稱為遙測報告，包括分析、稽核、帳單、記錄和監控。

Service Control API v2

Service Control API 第 2 版提供簡單的 services.report 方法，可向與服務基礎架構整合的所有服務提供遙測報告。這個方法可讓您在單一方法呼叫中執行下列操作：

  • 數據分析
  • 稽核
  • 帳單
  • 記錄
  • 監控

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