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 中指定的分桶数。如果您提供的值少于 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 的上限相同。分桶涵盖了整个有限值范围：下溢分桶的下限为 -infinity，上溢分桶的上限为 +infinity。之所以称为有限分桶，是因为其上下限都是有限的。

字段
联合字段 options。以下三个字段中，必须且只能设置一个。options 只能是下列其中一项：
linear_buckets

Linear

线性分桶。
exponential_buckets

Exponential

指数分桶。
explicit_buckets

Explicit

显式分桶。

露骨内容

指定一组宽度任意的分桶。

有 size(bounds) + 1 (= N) 个分桶。分桶 i 的边界如下：

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

bounds 字段必须至少包含一个元素。如果 bounds 只有一个元素，则没有有限分桶，并且该单个元素是上溢分桶和下溢分桶的共同边界。

字段
bounds[]

double

值必须单调递增。

指数

指定一个指数分桶序列，其宽度与下限值成正比。每个分桶都表示其内部特定值的一个恒定相对不确定性。

有 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。

线性

指定一个线性分桶序列，这些分桶都具有相同的宽度（上溢分桶和下溢分桶除外）。每个分桶都表示其内部特定值的一个恒定绝对不确定性。

有 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

第一个分桶的下限。

Exemplar

Exemplar 是可用于为汇总分布值添加注解的示例点。它们是元数据，可提供有关添加到分布分桶中的特定值的信息，例如添加值时处于活跃状态的跟踪 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 虚拟机实例，因为 "gce_instance" 的 MonitoredResourceDescriptor 具有标签 "project_id"、"instance_id" 和 "zone"：

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

string

必需。受监控的资源类型。此字段必须与 MonitoredResourceDescriptor 对象的 type 字段匹配。例如，Compute Engine 虚拟机实例的类型为 gce_instance。某些描述符会在类型中包含服务名称；例如，Datastream 流的类型为 datastream.googleapis.com/Stream。
labels

map<string, string>

必需。关联的受监控资源描述符中列出的所有标签的值。例如，Compute Engine 虚拟机实例使用标签 "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>

仅限输出。用户定义的元数据标签的映射。