Package google.api

索引

分布

Distribution 包含值母體的摘要統計資料。其中可選擇性包含直方圖，代表這些值在一組值區中的分布情形。

摘要統計資料包括值母體的計數、平均值、與平均值的平方偏差總和、最小值和最大值。直方圖是以一系列值區為基礎，並提供落入每個值區的值計數。範圍界限可明確指定，也可以透過公式計算，以取得固定或指數型遞增寬度的範圍。

雖然不禁止，但一般來說，在值母體中加入非有限值 (無限或 NaN) 並非好主意，因為這會使 mean 和 sum_of_squared_deviation 欄位變得毫無意義。

欄位
count

int64

母體中的值數量。不得為負值。如果提供直方圖，這個值必須等於 bucket_counts 中的值總和。
mean

double

母體中值的算術平均值。如果 count 為零，這個欄位就必須為零。
sum_of_squared_deviation

double

母體中各值與平均值偏差的平方和。對於值 x_i，這是：

Sum[i=1..n]((x_i - mean)^2)

Knuth 撰寫的「電腦程式設計的藝術」第 2 卷第 232 頁 (第 3 版) 說明瞭 Welford 的方法，可一次累加這個總和。

如果 count 為零，這個欄位就必須為零。
range

Range

如已指定，則包含母體值的範圍。如果 count 為零，則不得提供此欄位。
bucket_options

BucketOptions

定義直方圖值區界線。如果發布內容不含直方圖，請略過這個欄位。
bucket_counts[]

int64

直方圖中每個值區的值數量，如 bucket_options 所述。如果發布內容沒有直方圖，請略過這個欄位。如有直方圖，bucket_counts 中的值總和必須等於分配的 count 欄位值。

如有提供，bucket_counts 應包含 N 個值，其中 N 是 bucket_options 中指定的 bucket 數量。如果提供的數量少於 N 個值，系統會假設剩餘的值為 0。

bucket_counts 中的值順序會遵循三種值區類型所述的值區編號配置。第一個值必須是欠位值區的計數 (數字 0)。接下來的 N-2 個值是有限值區的計數 (數字 1 到 N-2)。bucket_counts 中的第 N 個值是溢位值區 (數字 N-1) 的計數。
exemplars[]

Exemplar

必須依 value 欄位遞增排序。

BucketOptions

BucketOptions 說明用於建立分布直方圖的範圍界線。值區可以是線性序列、指數序列，也可以明確指定每個值區。BucketOptions 不包含每個值區中的值數量。

值區的下限值 (含) 和上限值 (不含) 之間的值，都會計入該值區。值區上限必須嚴格大於下限。分布的 N 個值區序列包含欠位值區 (編號 0)、零或多個有限值區 (編號 1 到 N - 2) 和溢位值區 (編號 N - 1)。值區是連續的：值區 i (i > 0) 的下限與值區 i - 1 的上限相同。這些值區涵蓋整個有限值範圍：欠位值區的下界為負無限大，溢位值區的上界為正無限大。有限值區之所以稱為有限，是因為上下限都是有限值。

欄位
聯集欄位 options。必須設定這三個欄位中的其中一個。options 只能是下列其中一項：
linear_buckets

Linear

線性值區。
exponential_buckets

Exponential

指數值區。
explicit_buckets

Explicit

明確的 bucket。

明確

指定任意寬度的一組值區。

共有 size(bounds) + 1 (= N) 個值區。值區 i 有下列邊界：

上限 (0 <= i < N-1)：bounds[i] 下限 (1 <= i < N)：bounds[i - 1]

bounds 欄位必須包含至少一個元素。如果 bounds 只有一個元素，則沒有有限值區，而該單一元素是溢位和欠位值區的共同界線。

欄位
bounds[]

double

值必須單調遞增。

指數

指定寬度與下限值成正比的指數值區間序列。每個 bucket 代表 bucket 中特定值的相對不確定度常數。

共有 num_finite_buckets + 2 (= N) 個值區。值區 i 有下列邊界：

上限 (0 <= i < N-1)：scale * (growth_factor ^ i)。

下限 (1 <= i < N)：scale * (growth_factor ^ (i - 1))。

欄位
num_finite_buckets

int32

必須大於 0。
growth_factor

double

必須大於 1。
scale

double

必須大於 0。

線性

指定線性序列的 bucket，這些 bucket 的寬度都相同 (溢位和下溢除外)。每個值區代表值區中特定值的常數絕對不確定度。

共有 num_finite_buckets + 2 (= N) 個值區。值區 i 有下列邊界：

上限 (0 <= i < N-1)：offset + (width * i)。

下限 (1 <= i < N)：offset + (width * (i - 1))。

欄位
num_finite_buckets

int32

必須大於 0。
width

double

必須大於 0。
offset

double

第一個特徵分塊的下限。

範例

範例點可用於註解匯總的分布值。這些中繼資料會提供有關新增至 Distribution 值區的特定值資訊，例如新增值時處於活動狀態的追蹤 ID。可能包含更多資訊，例如範例值和時間戳記、來源等。

欄位
value

double

範例點的值。這個值會決定範例所屬的值區。
timestamp

Timestamp

上述值的觀察 (取樣) 時間。
attachments[]

Any

範例值的背景資訊。例如：

追蹤：type.googleapis.com/google.monitoring.v3.SpanContext

字串常值：type.googleapis.com/google.protobuf.StringValue

在彙整期間捨棄的標籤：type.googleapis.com/google.monitoring.v3.DroppedLabels

單一範例中，每種訊息類型只能有一個附件，這是系統強制執行的規定。

範圍

母體值的範圍。

欄位
min

double

母體值的最小值。
max

double

母體值的最大值。

HttpBody

用於表示任何 HTTP 主體的訊息；只能用於無法以 JSON 表示的酬載格式，例如未經處理的二進位檔或 HTML 網頁。

這個訊息可以用於要求及回應中的串流和非串流 API 方法。

這個訊息可以當做頂層要求欄位；想從網址或 HTTP 範本中將參數擷取至要求欄位，同時又想存取未經處理的 HTTP 主體時，這個做法就非常便利。

範例：

message GetResourceRequest {
  // A unique request id.
  string request_id = 1;

  // The raw HTTP body is bound to this field.
  google.api.HttpBody http_body = 2;

}

service ResourceService {
  rpc GetResource(GetResourceRequest)
    returns (google.api.HttpBody);
  rpc UpdateResource(google.api.HttpBody)
    returns (google.protobuf.Empty);

}

串流方法範例：

service CaldavService {
  rpc GetCalendar(stream google.api.HttpBody)
    returns (stream google.api.HttpBody);
  rpc UpdateCalendar(stream google.api.HttpBody)
    returns (stream google.api.HttpBody);

}

使用這個類型只會改變要求和回應主體的處理方式，所有其他功能的運作方式皆維持不變。

欄位
content_type

string

HTTP Content-Type 標頭值，用於指定主體的內容類型。
data

bytes

以原始二進位格式表示的 HTTP 要求/回應主體。
extensions[]

Any

應用程式專屬回應中繼資料。必須在串流 API 的第一個回應中進行設定。

指標

特定指標，透過為 MetricDescriptor 的所有標籤指定值來識別。

欄位
type

string

現有的指標類型，請參閱 google.api.MetricDescriptor。例如：custom.googleapis.com/invoice/paid/amount。
labels

map<string, string>

可唯一識別這個指標的標籤值組合。必須為 MetricDescriptor 中列出的所有標籤指派值。

MetricDescriptor

這個類型沒有任何欄位。

定義指標類型及其結構定義。建立指標描述元後，對其進行刪除或修改即會停止收集資料，並且使指標類型的現有資料變成無法使用。

MetricKind

測量的種類，其說明報告資料的方式。如要瞭解如何根據 MetricKind 設定開始時間和結束時間，請參閱 TimeInterval。

列舉
METRIC_KIND_UNSPECIFIED 請勿使用此預設值。
GAUGE 立即測量某個值。
DELTA 在時間間隔內某個值的變化。
CUMULATIVE 在時間間隔內累積的值。時間序列中的累計測量應具備相同的開始時間和增加的結束時間，直到事件將累計值重設為零，並且為後續點設定新的開始時間。

ValueType (值類型)

指標的值類型。

列舉
VALUE_TYPE_UNSPECIFIED 請勿使用此預設值。
BOOL 此值為布林值。只有當指標種類為 GAUGE 時，才能使用這個值類型。
INT64 此值為帶正負號的 64 位元整數。
DOUBLE 此值為雙精準度浮點數。
STRING 此值為文字字串。只有當指標種類為 GAUGE 時，才能使用這個值類型。
DISTRIBUTION 值為 Distribution。
MONEY 此值為金額。

MonitoredResource

這是一個物件，代表可用於監控、記錄、計費或其他用途的資源。相關範例包括：虛擬機器執行個體、資料庫，以及儲存裝置 (例如磁碟)。type 欄位會識別描述資源結構定義的 MonitoredResourceDescriptor 物件。labels 欄位中的資訊會根據結構定義，識別實際資源及其屬性。舉例來說，特定 Compute Engine VM 執行個體可由下列物件表示，因為 "gce_instance" 的標籤為 "project_id"、"instance_id" 和 "zone"：MonitoredResourceDescriptor

{ "type": "gce_instance",
  "labels": { "project_id": "my-project",
              "instance_id": "12345678901234",
              "zone": "us-central1-a" }}
欄位
type

string

這是必要旗標，受監控的資源類型。這個欄位必須與 MonitoredResourceDescriptor 物件的 type 欄位相符。舉例來說，Compute Engine VM 執行個體的類型為 gce_instance。部分描述元會在類型中加入服務名稱，例如 Datastream 串流的類型為 datastream.googleapis.com/Stream。
labels

map<string, string>

這是必要旗標，相關聯的受監控資源描述元中列出的所有標籤的值。舉例來說，Compute Engine VM 執行個體會使用 "project_id"、"instance_id" 和 "zone" 標籤。

MonitoredResourceMetadata

MonitoredResource 物件的輔助中繼資料。MonitoredResource 物件包含可明確識別受監控資源例項的最少資訊。另外還有一些有用的輔助中繼資料。Monitoring 和 Logging 透過擷取管道，為所有類型的雲端資源擷取中繼資料，並將中繼資料儲存在這則訊息中。

欄位
system_labels

Struct

僅限輸出。預先定義系統中繼資料標籤的值。系統標籤是一種由 Google 擷取的中繼資料，其中包括「machine_image」、「vpc」、「subnet_id」、「security_group」、「name」等。系統標籤值只能為字串、布林值或字串清單。例如：

{ "name": "my-test-instance",
  "security_group": ["a", "b", "c"],
  "spot_instance": false }
user_labels

map<string, string>

僅限輸出。使用者定義中繼資料標籤的對應區。