Package google.api

Índice

Distribuição

Distribution contém estatísticas resumidas para uma população de valores. Opcionalmente, contém um histograma que representa a distribuição desses valores num conjunto de contentores.

As estatísticas de resumo são a contagem, a média, a soma do desvio ao quadrado da média, o mínimo e o máximo do conjunto de valores da população. O histograma baseia-se numa sequência de segmentos e apresenta uma contagem de valores que se enquadram em cada segmento. Os limites dos grupos são fornecidos de forma explícita ou através de fórmulas para grupos de larguras fixas ou exponencialmente crescentes.

Embora não seja proibido, geralmente, é uma má ideia incluir valores não finitos (infinitos ou NaNs) na população de valores, uma vez que isto torna os campos mean e sum_of_squared_deviation sem significado.

Campos
count

int64

O número de valores na população. Tem de ser não negativo. Este valor tem de ser igual à soma dos valores em bucket_counts se for fornecido um histograma.
mean

double

A média aritmética dos valores na população. Se count for zero, este campo tem de ser zero.
sum_of_squared_deviation

double

A soma dos desvios quadrados da média dos valores na população. Para os valores x_i, isto é:

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

Knuth, "The Art of Computer Programming", Vol. 2, página 232, 3.ª edição, descreve o método de Welford para acumular esta soma numa única passagem.

Se count for zero, este campo tem de ser zero.
range

Range

Se especificado, contém o intervalo dos valores da população. O campo não pode estar presente se o valor de count for zero.
bucket_options

BucketOptions

Define os limites dos intervalos do histograma. Se a distribuição não contiver um histograma, omita este campo.
bucket_counts[]

int64

O número de valores em cada segmento do histograma, conforme descrito em bucket_options. Se a distribuição não tiver um histograma, omita este campo. Se existir um histograma, a soma dos valores em bucket_counts tem de ser igual ao valor no campo count da distribuição.

Se estiver presente, bucket_counts deve conter N valores, em que N é o número de grupos especificados em bucket_options. Se fornecer menos de N valores, considera-se que os valores restantes são 0.

A ordem dos valores em bucket_counts segue os esquemas de numeração de contentores descritos para os três tipos de contentores. O primeiro valor tem de ser a contagem do intervalo de underflow (número 0). Os N-2 valores seguintes são as contagens dos intervalos finitos (número 1 a N-2). O N-ésimo valor em bucket_counts é a contagem do recipiente de overflow (número N-1).
exemplars[]

Exemplar

Tem de estar por ordem crescente do campo value.

BucketOptions

BucketOptions descreve os limites dos contentores usados para criar um histograma para a distribuição. Os intervalos podem estar numa sequência linear, numa sequência exponencial ou cada intervalo pode ser especificado explicitamente. BucketOptions não inclui o número de valores em cada segmento.

Um segmento tem um limite inferior inclusivo e um limite superior exclusivo para os valores que são contabilizados para esse segmento. O limite superior de um grupo tem de ser estritamente superior ao limite inferior. A sequência de N contentores para uma distribuição consiste num contentor de limite inferior (número 0), zero ou mais contentores finitos (número 1 a N - 2) e um contentor de limite superior (número N - 1). Os intervalos são contíguos: o limite inferior do intervalo i (i > 0) é igual ao limite superior do intervalo i - 1. Os segmentos abrangem todo o intervalo de valores finitos: o limite inferior do segmento de underflow é -infinito e o limite superior do segmento de overflow é +infinito. Os intervalos finitos são assim denominados porque ambos os limites são finitos.

Campos
Campo de união options. Tem de definir exatamente um destes três campos. options só pode ser uma das seguintes opções:
linear_buckets

Linear

O intervalo linear.
exponential_buckets

Exponential

Os intervalos exponenciais.
explicit_buckets

Explicit

Os contentores explícitos.

Explícito

Especifica um conjunto de intervalos com larguras arbitrárias.

Existem size(bounds) + 1 (= N) contentores. O intervalo i tem os seguintes limites:

Limite superior (0 <= i < N-1): bounds[i] Limite inferior (1 <= i < N); bounds[i - 1]

O campo bounds tem de conter, pelo menos, um elemento. Se bounds tiver apenas um elemento, não existem intervalos finitos e esse único elemento é o limite comum dos intervalos de excesso e de falta.

Campos
bounds[]

double

Os valores têm de aumentar monotonicamente.

Exponencial

Especifica uma sequência exponencial de segmentos que têm uma largura proporcional ao valor do limite inferior. Cada contentor representa uma incerteza relativa constante num valor específico no contentor.

Existem num_finite_buckets + 2 (= N) contentores. O intervalo i tem os seguintes limites:

Limite superior (0 <= i < N-1): scale * (growth_factor ^ i).

Limite inferior (1 <= i < N): scale * (growth_factor ^ (i - 1)).

Campos
num_finite_buckets

int32

Tem de ser superior a 0.
growth_factor

double

Tem de ser superior a 1.
scale

double

Tem de ser superior a 0.

Linear

Especifica uma sequência linear de grupos que têm todos a mesma largura (exceto o excesso e a falta). Cada contentor representa uma incerteza absoluta constante no valor específico no contentor.

Existem num_finite_buckets + 2 (= N) contentores. O intervalo i tem os seguintes limites:

Limite superior (0 <= i < N-1): deslocamento + (largura * i).

Limite inferior (1 <= i < N): deslocamento + (largura * (i - 1)).

Campos
num_finite_buckets

int32

Tem de ser superior a 0.
width

double

Tem de ser superior a 0.
offset

double

Limite inferior do primeiro grupo.

Exemplar

Os exemplares são pontos de exemplo que podem ser usados para anotar valores de distribuição agregados. São metadados que fornecem informações sobre um valor específico adicionado a um depósito de distribuição, como um ID de rastreio que estava ativo quando foi adicionado um valor. Podem conter mais informações, como valores de exemplo e datas/horas, origem, etc.

Campos
value

double

Valor do ponto exemplar. Este valor determina a que grupo pertence o exemplo.
timestamp

Timestamp

A hora de observação (amostragem) do valor acima.
attachments[]

Any

Informações contextuais sobre o valor de exemplo. Exemplos:

Trace: type.googleapis.com/google.monitoring.v3.SpanContext

String literal: type.googleapis.com/google.protobuf.StringValue

Etiquetas ignoradas durante a agregação: type.googleapis.com/google.monitoring.v3.DroppedLabels

Pode existir apenas um anexo de qualquer tipo de mensagem num único exemplo, e isto é aplicado pelo sistema.

Intervalo

O intervalo dos valores da população.

Campos
min

double

O mínimo dos valores da população.
max

double

O máximo dos valores da população.

HttpBody

Mensagem que representa um corpo HTTP arbitrário. Só deve ser usado para formatos de carga útil que não podem ser representados como JSON, como binário não processado ou uma página HTML.

Esta mensagem pode ser usada em métodos de API de streaming e não streaming no pedido, bem como na resposta.

Pode ser usado como um campo de pedido de nível superior, o que é conveniente se quiser extrair parâmetros do URL ou do modelo HTTP para os campos de pedido e também quiser aceder ao corpo HTTP não processado.

Exemplo:

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);

}

Exemplo com métodos de streaming:

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

}

A utilização deste tipo só altera a forma como os corpos do pedido e da resposta são processados. Todas as outras funcionalidades continuam a funcionar sem alterações.

Campos
content_type

string

O valor do cabeçalho Content-Type HTTP que especifica o tipo de conteúdo do corpo.
data

bytes

O corpo do pedido/resposta HTTP como binário não processado.
extensions[]

Any

Metadados de resposta específicos da aplicação. Tem de ser definido na primeira resposta para APIs de streaming.

Métrica

Uma métrica específica, identificada pela especificação de valores para todas as etiquetas de um MetricDescriptor.

Campos
type

string

Um tipo de métrica existente. Consulte google.api.MetricDescriptor. Por exemplo, custom.googleapis.com/invoice/paid/amount.
labels

map<string, string>

O conjunto de valores de etiquetas que identificam exclusivamente esta métrica. É necessário atribuir valores a todas as etiquetas apresentadas em MetricDescriptor.

MetricDescriptor

Este tipo não tem campos.

Define um tipo de métrica e o respetivo esquema. Depois de criar um descritor de métricas, a eliminação ou a alteração do mesmo interrompe a recolha de dados e torna os dados existentes do tipo de métrica inutilizáveis.

MetricKind

O tipo de medição. Descreve como os dados são comunicados. Para informações sobre como definir a hora de início e a hora de fim com base no MetricKind, consulte TimeInterval.

Enumerações
METRIC_KIND_UNSPECIFIED Não use este valor predefinido.
GAUGE Uma medição instantânea de um valor.
DELTA A alteração num valor durante um intervalo de tempo.
CUMULATIVE Um valor acumulado ao longo de um intervalo de tempo. As medições cumulativas numa série cronológica devem ter a mesma hora de início e horas de fim crescentes, até que um evento repõe o valor cumulativo para zero e define uma nova hora de início para os pontos seguintes.

ValueType

O tipo de valor de uma métrica.

Enumerações
VALUE_TYPE_UNSPECIFIED Não use este valor predefinido.
BOOL O valor é um booleano. Este tipo de valor só pode ser usado se o tipo de métrica for GAUGE.
INT64 O valor é um número inteiro de 64 bits com sinal.
DOUBLE O valor é um número de vírgula flutuante de precisão dupla.
STRING O valor é uma string de texto. Este tipo de valor só pode ser usado se o tipo de métrica for GAUGE.
DISTRIBUTION O valor é Distribution.
MONEY O valor é dinheiro.

MonitoredResource

Um objeto que representa um recurso que pode ser usado para monitorização, registo, faturação ou outros fins. Os exemplos incluem instâncias de máquinas virtuais, bases de dados e dispositivos de armazenamento, como discos. O campo type identifica um objeto MonitoredResourceDescriptor que descreve o esquema do recurso. As informações no campo labels identificam o recurso real e os respetivos atributos de acordo com o esquema. Por exemplo, uma instância de VM do Compute Engine específica pode ser representada pelo seguinte objeto, porque o MonitoredResourceDescriptor para "gce_instance" tem as etiquetas "project_id", "instance_id" e "zone":

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

string

Obrigatório. O tipo de recurso monitorizado. Este campo tem de corresponder ao campo type de um objeto MonitoredResourceDescriptor. Por exemplo, o tipo de uma instância de VM do Compute Engine é gce_instance. Alguns descritores incluem o nome do serviço no tipo; por exemplo, o tipo de uma stream do Datastream é datastream.googleapis.com/Stream.
labels

map<string, string>

Obrigatório. Valores de todas as etiquetas apresentadas no descritor de recursos monitorizados associado. Por exemplo, as instâncias de VM do Compute Engine usam as etiquetas "project_id", "instance_id" e "zone".

MonitoredResourceMetadata

Metadados auxiliares para um objeto MonitoredResource. Os objetos MonitoredResource contêm o conjunto mínimo de informações para identificar de forma exclusiva uma instância de recurso monitorizada. Existem outros metadados auxiliares úteis. A monitorização e o registo usam um pipeline de carregamento para extrair metadados de recursos na nuvem de todos os tipos e armazenam os metadados nesta mensagem.

Campos
system_labels

Struct

Apenas saída. Valores para etiquetas de metadados do sistema predefinidas. As etiquetas do sistema são um tipo de metadados extraídos pela Google, incluindo "machine_image", "vpc", "subnet_id", "security_group", "name", etc. Os valores das etiquetas do sistema só podem ser strings, valores booleanos ou uma lista de strings. Por exemplo:

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

map<string, string>

Apenas saída. Um mapa de etiquetas de metadados definidos pelo utilizador.