Package google.api

索引

• Distribution（消息）
• Distribution.BucketOptions（消息）
• Distribution.BucketOptions.Explicit（消息）
• Distribution.BucketOptions.Exponential（消息）
• Distribution.BucketOptions.Linear（消息）
• Distribution.Exemplar（消息）
• Distribution.Range（消息）
• HttpBody（消息）
• Metric（消息）
• MetricDescriptor（消息）
• MetricDescriptor.MetricKind（枚举）
• MetricDescriptor.ValueType（枚举）
• MonitoredResource（消息）
• MonitoredResourceMetadata（消息）

分布

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

范例是可用于注释汇总分布值的示例点。它们是元数据，用于提供有关添加到分布桶中的特定值的信息，例如添加值时处于活跃状态的轨迹 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> 仅限输出。用户定义的元数据标签的映射。