Pacote google.api

Index

AuthProvider

Configuração para um provedor de autenticação, inclusive suporte a JSON Web Token (JWT).

Campos
id

string

O identificador exclusivo do provedor de autenticação. Será referenciado por AuthRequirement.provider_id.

Exemplo: "bookstore_auth".

issuer

string

Identifica o principal que emitiu o JWT. Consulte https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1. Geralmente um URL ou um endereço de e-mail.

Exemplo: https://securetoken.google.com

Exemplo: 1234567-compute@developer.gserviceaccount.com

jwks_uri

string

URL do conjunto de chaves públicas do provedor para validar a assinatura do JWT. consulte a OpenID Discovery. Opcional se o documento do conjunto de chaves: - puder ser recuperado em [OpenID Discovery] (https://openid.net/specs/openid-connect-discovery-1_0.html) do emissor; - puder ser inferido a partir do domínio de e-mail do emissor (por exemplo, uma conta de serviço do Google).

Exemplo: https://www.googleapis.com/oauth2/v1/certs

audiences

string

A lista de públicos-alvo do JWT que têm acesso permitido. Será aceito um JWT que contenha algum desses públicos-alvo. Quando essa configuração estiver ausente, apenas JWTs com os públicos-alvo "https://Service_name/API_name" serão aceitos. Por exemplo, se nenhum público-alvo estiver definido na configuração, a API LibraryService só aceitará JWTs com o público-alvo "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

Exemplo:


audiences: bookstore_android.apps.googleusercontent.com,
           bookstore_web.apps.googleusercontent.com

authorization_url

string

URL de redirecionamento se o token JWT for necessário, mas não estiver presente ou estiver expirado. Implementa authorizationUrl de securityDefinitions nas especificações da OpenAPI.

AuthRequirement

Requisitos de autenticação definidos pelo usuário, inclusive suporte a JSON Web Token (JWT).

Campos
provider_id

string

id do provedor de autenticação.

Exemplo:


provider_id: bookstore_auth

audiences

string

OBSERVAÇÃO: terá o uso suspenso em breve, assim que AuthProvider.audiences for implementado e aceito em todos os componentes de tempo de execução.

A lista de públicos-alvo do JWT que têm acesso permitido. Será aceito um JWT que contenha algum desses públicos-alvo. Quando essa configuração estiver ausente, apenas JWTs com os públicos-alvo "https://Service_name/API_name" serão aceitos. Por exemplo, se nenhum público-alvo estiver definido na configuração, a API LibraryService só aceitará JWTs com o público-alvo "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

Exemplo:


audiences: bookstore_android.apps.googleusercontent.com,
           bookstore_web.apps.googleusercontent.com

Authentication

Authentication define a configuração de autenticação de uma API.

Exemplo de uma API direcionada para uso externo:

name: calendar.googleapis.com
authentication:
  providers:
  - id: google_calendar_auth
    jwks_uri: https://www.googleapis.com/oauth2/v1/certs
    issuer: https://securetoken.google.com
  rules:
  - selector: "*"
    requirements:
      provider_id: google_calendar_auth
Campos
rules[]

AuthenticationRule

Uma lista de regras de autenticação aplicáveis aos métodos individuais da API.

OBSERVAÇÃO: todas as regras de configuração do serviço seguem a ordem "vale a última opção".

providers[]

AuthProvider

Define um conjunto de provedores de autenticação que um serviço oferece.

AuthenticationRule

Regras de autenticação para o serviço.

Por padrão, se um método tiver quaisquer requisitos de autenticação, cada solicitação precisa incluir uma credencial válida que corresponda a um dos requisitos. É um erro incluir mais de um tipo de credencial em uma única solicitação.

Se um método não tiver requisitos de autenticação, as credenciais de solicitação serão ignoradas.

Campos
selector

string

Seleciona os métodos aos quais esta regra se aplica.

Consulte o selector para detalhes da sintaxe.

requirements[]

AuthRequirement

Requisitos para provedores de autenticação adicionais.

CustomHttpPattern

Para definir o verbo HTTP personalizado, usa-se um padrão personalizado.

Campos
kind

string

O nome desse verbo HTTP personalizado.

path

string

O caminho correspondente a esse verbo personalizado.

Documentation

Documentation fornece informações para descrever um serviço.

Exemplo:

documentation:
  summary: >
    The Google Calendar API gives access
    to most calendar features.
  pages:
  - name: Overview
    content: (== include google/foo/overview.md ==)
  - name: Tutorial
    content: (== include google/foo/tutorial.md ==)
    subpages;
    - name: Java
      content: (== include google/foo/tutorial_java.md ==)
  rules:
  - selector: google.calendar.Calendar.Get
    description: >
      ...
  - selector: google.calendar.Calendar.Put
    description: >
      ...

A documentação é fornecida na sintaxe do Markdown. Além dos recursos padrão do Markdown, listas de definições, tabelas e blocos de código delimitados são aceitos. Os cabeçalhos de seção podem ser fornecidos e são interpretados em relação ao aninhamento de seção do contexto em que um fragmento de documentação está incorporado.

A documentação do IDL é mesclada com a documentação definida por meio da configuração no horário de normalização, onde a documentação fornecida pelas regras de configuração substitui o IDL fornecido.

Uma série de construções específicas da plataforma da API são aceitas no texto da documentação.

Para fazer referência a um elemento proto, a seguinte notação pode ser usada:

[fully.qualified.proto.name][]

Para substituir o texto de exibição usado no link, é possível usar o seguinte:

[display text][fully.qualified.proto.name]

O texto pode ser excluído do documento por meio da seguinte notação:

(-- internal comment --)

Os comentários podem ser condicionais com um rótulo de visibilidade. O texto abaixo será renderizado apenas se o rótulo BETA estiver disponível:

(--BETA: comment for BETA users --)

Algumas diretrizes estão disponíveis na documentação. Observe que as diretrizes precisam aparecer em uma única linha para serem devidamente identificadas. A diretiva include inclui um arquivo do Markdown de uma fonte externa:

(== include path/to/file ==)

A diretriz resource_for marca uma mensagem para ser o recurso de uma coleção na visualização REST. Se não for especificada, as ferramentas tentam inferir o recurso das operações em uma coleção:

(== resource_for v1.shelves.books ==)

A diretiva suppress_warning não afeta diretamente a documentação e é documentada em conjunto com a validação da configuração do serviço.

Campos
summary

string

Um breve resumo do que o serviço faz. Só pode ser fornecido por texto simples.

pages[]

Page

As páginas de nível superior do conjunto de documentação.

rules[]

DocumentationRule

Uma lista de regras de documentação que se aplicam a elementos individuais da API.

OBSERVAÇÃO: todas as regras de configuração do serviço seguem a ordem "vale a última opção".

documentation_root_url

string

O URL para a raiz da documentação.

overview

string

Declara uma única página de visão geral. Exemplo:


documentation:
  summary: ...
  overview: (== include overview.md ==)

Este é um atalho para a seguinte declaração (usando estilo de páginas):


documentation:
  summary: ...
  pages:
  - name: Overview
    content: (== include overview.md ==)

Observação: não é possível especificar os campos overview e pages.

DocumentationRule

Uma regra de documentação que fornece informações sobre elementos individuais da API.

Campos
selector

string

O seletor é uma lista de padrões separada por vírgulas. Cada padrão é um nome qualificado do elemento que pode terminar em "*", indicando um curinga. Os caracteres curinga só são permitidos no final e para um componente completo do nome qualificado. Por exemplo, "foo.*" é aceito, mas "foo.b*" ou "foo.*.bar" não. Para especificar um padrão para todos os elementos aplicados, o padrão "*" é usado.

description

string

Descrição das APIs selecionadas.

deprecation_description

string

Descrição de suspensão do uso dos elementos selecionados. Pode ser fornecida se um elemento for marcado como deprecated.

Endpoint

Endpoint descreve um ponto de extremidade da rede que atende um conjunto de APIs. Um serviço pode expor qualquer número de pontos de extremidade, e todos os pontos de extremidade compartilham a mesma configuração de serviço, como configuração de cota e de monitoramento.

Exemplo de configuração de serviço:

name: library-example.googleapis.com
endpoints:
  # Below entry makes 'google.example.library.v1.Library'
  # API be served from endpoint address library-example.googleapis.com.
  # It also allows HTTP OPTIONS calls to be passed to the backend, for
  # it to decide whether the subsequent cross-origin request is
  # allowed to proceed.
- name: library-example.googleapis.com
  allow_cors: true
Campos
name

string

O nome canônico desse ponto de extremidade.

allow_cors

bool

Permitir o CORS, ou tráfego entre domínios, possibilita que os back-ends servidos a partir desse ponto de extremidade recebam e respondam a solicitações HTTP OPTIONS. A resposta será usada pelo navegador para determinar se a solicitação subsequente de origem cruzada pode continuar.

Http

Define a configuração de HTTP para um serviço de API. Ele contém uma lista de HttpRule, em que cada uma especifica o mapeamento de um método RPC para um ou mais métodos API HTTP REST.

Campos
rules[]

HttpRule

Uma lista de regras de configuração de HTTP que se aplicam a métodos de API individuais.

OBSERVAÇÃO: todas as regras de configuração do serviço seguem a ordem "vale a última opção".

fully_decode_reserved_expansion

bool

Quando definido como true, os parâmetros de caminho de URL serão totalmente decodificados pelo URI, exceto nos casos de correspondências de segmento único em expansão reservada. Nesses casos, "% 2F" permanecerá codificado.

O comportamento padrão é não decodificar os caracteres reservados do RFC 6570 em correspondências de vários segmentos.

HttpRule

HttpRule define o mapeamento de um método RPC para um ou mais métodos da API HTTP REST. O mapeamento especifica como partes diferentes da mensagem de solicitação RPC são mapeadas para o caminho do URL, os parâmetros de consulta do URL e o corpo de solicitação HTTP. O mapeamento é normalmente especificado como uma anotação google.api.http no método RPC, veja "google/api/annotations.proto" para saber mais detalhes.

O mapeamento consiste em um campo que especifica o modelo de caminho e o tipo de método. O modelo de caminho pode indicar campos na mensagem de solicitação, como no exemplo abaixo, que descreve uma operação REST GET em um conjunto de recursos de mensagens:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";
  }
}
message GetMessageRequest {
  message SubMessage {
    string subfield = 1;
  }
  string message_id = 1; // mapped to the URL
  SubMessage sub = 2;    // `sub.subfield` is url-mapped
}
message Message {
  string text = 1; // content of the resource
}

De forma alternativa, a mesma anotação http pode ser expressa dentro do arquivo YAML da GRPC API Configuration.

http:
  rules:
    - selector: <proto_package_name>.Messaging.GetMessage
      get: /v1/messages/{message_id}/{sub.subfield}

Essa definição ativa um mapeamento bidirecional automático de HTTP JSON para RPC. Exemplo:

HTTP RPC
GET /v1/messages/123456/foo GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))

Em geral, não apenas os campos, mas os caminhos de campo também podem ser referenciados a partir de um padrão de caminho. Os campos mapeados para o padrão de caminho não podem ser repetidos e devem ter um tipo primitivo (sem mensagem).

Na mensagem de solicitação, qualquer campo que não estiver vinculado pelo padrão de caminho se torna automaticamente um parâmetro de consulta HTTP (opcional). Observe a seguinte definição da mensagem de solicitação:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http).get = "/v1/messages/{message_id}";
  }
}
message GetMessageRequest {
  message SubMessage {
    string subfield = 1;
  }
  string message_id = 1; // mapped to the URL
  int64 revision = 2;    // becomes a parameter
  SubMessage sub = 3;    // `sub.subfield` becomes a parameter
}

Essa definição permite um mapeamento HTTP JSON para RPC, conforme mostramos abaixo:

HTTP RPC
GET /v1/messages/123456?revision=2&sub.subfield=foo GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))

Observe que os campos mapeados para parâmetros HTTP devem ter um tipo primitivo ou um tipo primitivo repetido. Tipos de mensagens não são permitidos. No caso de um tipo repetido, o parâmetro pode ser repetido no URL, como em ...?param=A&param=B.

Para tipos de métodos HTTP que permitem um corpo de solicitação, o campo body especifica o mapeamento. Considere um método de atualização REST na coleção de recursos da mensagem:

service Messaging {
  rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
    option (google.api.http) = {
      put: "/v1/messages/{message_id}"
      body: "message"
    };
  }
}
message UpdateMessageRequest {
  string message_id = 1; // mapped to the URL
  Message message = 2;   // mapped to the body
}

O mapeamento HTTP JSON to RPC a seguir está ativado. A representação do JSON no corpo da solicitação é determinada pela codificação de protos JSON:

HTTP RPC
PUT /v1/messages/123456 { "text": "Hi!" } UpdateMessage(message_id: "123456" message { text: "Hi!" })

O nome especial * pode ser usado no mapeamento do corpo para definir que cada campo não vinculado ao modelo de caminho deve ser mapeado para o corpo da solicitação. Isso permite a seguinte definição alternativa do método de atualização.

service Messaging {
  rpc UpdateMessage(Message) returns (Message) {
    option (google.api.http) = {
      put: "/v1/messages/{message_id}"
      body: "*"
    };
  }
}
message Message {
  string message_id = 1;
  string text = 2;
}

O mapeamento HTTP JSON to RPC a seguir está ativado:

HTTP RPC
PUT /v1/messages/123456 { "text": "Hi!" } UpdateMessage(message_id: "123456" text: "Hi!")

Observe que ao usar * no mapeamento do corpo, não é possível ter parâmetros HTTP, porque todos os campos não vinculados pelo caminho terminam no corpo. Isso faz com que essa opção seja pouco usada na prática da definição de APIs REST. O uso mais comum de * é em métodos personalizados, que não usam o URL para transferir dados.

É possível definir vários métodos HTTP para um RPC usando a opção additional_bindings . Exemplo:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http) = {
      get: "/v1/messages/{message_id}"
      additional_bindings {
        get: "/v1/users/{user_id}/messages/{message_id}"
      }
    };
  }
}
message GetMessageRequest {
  string message_id = 1;
  string user_id = 2;
}

Isso permite os dois mapeamentos HTTP JSON a RPC alternativos a seguir:

HTTP RPC
GET /v1/messages/123456 GetMessage(message_id: "123456")
GET /v1/users/me/messages/123456 GetMessage(user_id: "me" message_id: "123456")

Regras para o mapeamento de HTTP

As regras para mapeamento de caminho HTTP, parâmetros de consulta e campos do corpo para a mensagem de solicitação são as seguintes:

  1. O campo body especifica *, um caminho de campo ou é omitido. Se omitido, indica que não há corpo de solicitação HTTP.
  2. Os campos folha (expansão recursiva de mensagens aninhadas na solicitação) podem ser classificados em três tipos: (a) Correspondido no modelo de URL. (b) Coberto por corpo (se body for * , tudo exceto os campos do tipo (a); se não, tudo sob o campo body). (c) Todos os outros campos.
  3. Os parâmetros de consulta de URL encontrados na solicitação HTTP são mapeados para os campos (c).
  4. Qualquer corpo enviado com uma solicitação HTTP pode conter apenas campos (b).

A sintaxe do modelo de caminho é a seguinte:

Template = "/" Segments [ Verb ] ;
Segments = Segment { "/" Segment } ;
Segment  = "*" | "**" | LITERAL | Variable ;
Variable = "{" FieldPath [ "=" Segments ] "}" ;
FieldPath = IDENT { "." IDENT } ;
Verb     = ":" LITERAL ;

A sintaxe * corresponde a um único segmento de caminho. A sintaxe ** corresponde a zero ou mais segmentos de caminho, que devem ser a última parte do caminho, exceto o Verb. A sintaxe LITERAL corresponde ao texto literal no caminho.

A sintaxe Variable corresponde a parte do caminho da URL, conforme especificado por seu modelo. Um modelo de variável não deve conter outras variáveis. Se uma variável corresponder a um único segmento de caminho, seu modelo pode ser omitido. Por exemplo, {var} é equivalente a {var=*}.

Se uma variável contiver exatamente um segmento de caminho, como "{var}" ou "{var=*}", quando essa variável for expandida em um caminho de URL, todos os caracteres, exceto [-_.~0-9a-zA-Z], são percentualmente codificados. Essas variáveis aparecem no Documento de descoberta como {var}.

Se uma variável contiver um ou mais segmentos de caminho, como "{var=foo/*}" ou "{var=**}" , quando essa variável for expandida em um caminho de URL, todos os caracteres, exceto [-_.~/0-9a-zA-Z], são percentualmente codificados. Essas variáveis aparecem no Documento de descoberta como {+var}.

Observação: Embora a variável de segmento único corresponda à semântica da Expansão de strings simples do RFC 6570,Seção 3.2.2, a variável de segmentos múltiplos não corresponde à Expansão reservada do RFC 6570. Isso acontece porque a Expansão reservada não expande caracteres especiais como ? e #, o que levaria a URLs inválidos.

Observação: os caminhos de campo nas variáveis e no body não devem se referir a campos repetidos ou a campos de mapa.

Campos
selector

string

Seleciona os métodos aos quais esta regra se aplica.

Consulte o selector para detalhes da sintaxe.

body

string

O nome do campo de solicitação cujo valor é mapeado para o corpo HTTP ou * para mapear todos os campos que não são capturados pelo padrão de caminho para o corpo HTTP. Observação: o campo referido não pode ser um campo repetido e deve estar presente no nível superior do tipo de mensagem de solicitação.

additional_bindings[]

HttpRule

Outras vinculações HTTP para o seletor. As vinculações aninhadas não podem conter um campo additional_bindings, ou seja, o aninhamento pode ter apenas um nível de profundidade.

rest_collection

string

NÃO USE. Este é um campo experimental.

Opcional. Por padrão, o nome da coleção REST é derivado do padrão do URL. Se for especificado, esse campo substituirá o nome padrão da coleção. Exemplo:


rpc AddressesAggregatedList(AddressesAggregatedListRequest)
    returns (AddressesAggregatedListResponse) {
  option (google.api.http) = {
    get: "/v1/projects/{project_id}/aggregated/addresses"
    rest_collection: "projects.addresses"
  };
}

Este método tem o nome da coleção "projects.aggregated", derivado de forma automática. Semanticamente, esse rpc é na verdade uma operação na coleção "projects.addresses". Por isso, o campo rest_collection é configurado para substituir o nome da coleção derivado.

rest_method_name

string

NÃO USE. Este é um campo experimental.

Opcional. Por padrão, o nome do método REST é derivado do padrão do URL. Se for especificado, esse campo substituirá o nome do método padrão. Exemplo:


rpc CreateResource(CreateResourceRequest)
    returns (CreateResourceResponse) {
  option (google.api.http) = {
    post: "/v1/resources",
    body: "resource",
    rest_method_name: "insert"
  };
}

Esse método tem o nome do método REST "create" derivado automaticamente, mas, para compatibilidade com versões anteriores do Apiary, ele é especificado como insert.

Campo de união pattern. Determina que o padrão do URL seja correspondido por essas regras. Esse padrão pode ser usado com qualquer um dos métodos {get | put | post | delete | patch}. É possível definir um método personalizado usando o campo "custom". pattern pode ser apenas um dos seguintes:
get

string

Usado para listar e receber informações sobre recursos.

put

string

Usado para atualizar um recurso.

post

string

Usado para criar um recurso.

delete

string

Usado para excluir um recurso.

patch

string

Usado para atualizar um recurso.

custom

CustomHttpPattern

O padrão personalizado é usado para especificar um método HTTP que não está incluído no campo pattern, como HEAD, ou "*" para deixar o método HTTP não especificado para essa regra. A regra curinga é útil para serviços que fornecem conteúdo para clientes Web (HTML).

LabelDescriptor

Descrição de um rótulo.

Campos
key

string

A chave de rótulo

value_type

ValueType

O tipo de dados que pode ser atribuído ao rótulo.

description

string

Uma descrição legível para o rótulo.

ValueType

Tipos de valor que podem ser usados como valores de rótulo.

Enums
STRING Uma string de comprimento variável. Esse é o padrão.
BOOL Booleano, verdadeiro ou falso.
INT64 Um número inteiro assinado de 64 bits

MetricDescriptor

Define um tipo de métrica e seu esquema. Depois que um descritor de métrica é criado, sua exclusão ou alteração interrompe a coleta de dados e torna os dados existentes do tipo de métrica inutilizáveis.

Campos
name

string

O nome do recurso do descritor de métrica.

type

string

O tipo de métrica, incluindo seu prefixo de nome DNS. O tipo não é codificado por URL. Todos os tipos de métrica personalizados definidos pelo usuário têm o nome DNS custom.googleapis.com. Tipos de métrica devem usar um agrupamento hierárquico natural. Exemplo:


"custom.googleapis.com/invoice/paid/amount"
"appengine.googleapis.com/http/server/response_latencies"

labels[]

LabelDescriptor

O conjunto de rótulos que pode ser usado para descrever uma instância específica desse tipo de métrica. Por exemplo, o tipo de métrica appengine.googleapis.com/http/server/response_latencies tem um rótulo para o código de resposta HTTP, response_code, para que você possa analisar as latências de respostas bem-sucedidas ou apenas as respostas com falha.

metric_kind

MetricKind

Indica se a métrica registra valores instantâneos, alterações em um valor, etc. Algumas combinações de metric_kind e value_type podem não ser compatíveis.

value_type

ValueType

Indica se a medida é um número inteiro, um número de ponto flutuante, etc. Algumas combinações de metric_kind e value_type podem não ser compatíveis.

unit

string

A unidade em que o valor da métrica é relatado. Aplicável apenas se o value_type for INT64 , DOUBLE ou DISTRIBUTION. As unidades compatíveis são um subconjunto do padrão do Código unificado para unidades de medida (em inglês):

Unidades básicas (UNIT)

  • bit bit
  • By byte
  • s: segundo
  • min minuto
  • h: hora
  • d: dia

Prefixos (PREFIX)

  • k quilo (10 ** 3)
  • M mega (10 ** 6)
  • G giga (10 ** 9)
  • T tera (10 ** 12)
  • P peta (10 ** 15)
  • E exa (10 ** 18)
  • Z zetta (10 ** 21)
  • Y yotta (10 ** 24)
  • m milli (10 ** - 3)
  • u micro (10 ** - 6)
  • n nano (10 ** - 9)
  • p pico (10 ** - 12)
  • f femto (10 ** - 15)
  • a atto (10 ** - 18)
  • z zepto (10 ** - 21)
  • y yocto (10 ** - 24)
  • Ki kibi (2 ** 10)
  • Mi mebi (2 ** 20)
  • Gi gibi (2 ** 30)
  • Ti tebi (2 ** 40)

Gramática

A gramática inclui a unidade sem dimensão 1, como 1/s.

A gramática também inclui os seguintes conectores:

  • / divisão (como um operador infixo, por exemplo, 1/s).
  • . multiplicação (como um operador infixo, por exemplo, GBy.d)

Veja abaixo a gramática de uma unidade:


Expression = Component { "." Component } { "/" Component } ;

Component = [ PREFIX ] UNIT [ Annotation ]
          | Annotation
          | "1"
          ;

Annotation = "{" NAME "}" ;

Observações:

  • Annotation é apenas um comentário se acompanha uma UNIT. É equivalente a 1 se for usado sozinho. Por exemplo, {requests}/s == 1/s e By{transmitted}/s == By/s.
  • NAME é uma sequência de caracteres ASCII não vazios e imprimíveis que não contém "{' ou '}".

description

string

Uma descrição detalhada da métrica, que pode ser usada na documentação.

display_name

string

Um nome conciso para a métrica, que pode ser exibido nas interfaces do usuário. Use a primeira letra maiúscula e não adicione ponto final. Por exemplo, "Contagem de solicitações". Este campo é opcional, mas é recomendado que seja definido para qualquer métrica associada a conceitos visíveis ao usuário, como a Cota.

MetricKind

Um tipo de medida. Descreve como os dados são reportados.

Enums
METRIC_KIND_UNSPECIFIED Não use este valor padrão.
GAUGE Uma medida instantânea de um valor.
DELTA A alteração em um valor durante um intervalo de tempo.
CUMULATIVE Um valor acumulado ao longo de um intervalo de tempo. As medidas cumulativas em uma sequência temporal devem ter o mesmo horário de início e horários de término crescentes até que um evento redefina o valor cumulativo para zero e defina um novo horário de início para os pontos posteriores.

ValueType

O tipo de valor de uma métrica.

Enums
VALUE_TYPE_UNSPECIFIED Não use este valor padrão.
BOOL O valor é um booleano. Esse tipo de valor pode ser usado apenas se o tipo de métrica for GAUGE.
INT64 O valor é um número inteiro assinado de 64 bits.
DOUBLE O valor é um número de ponto flutuante de precisão dupla.
STRING O valor é uma string de texto. Esse tipo de valor pode ser usado apenas se o tipo de métrica for GAUGE.
DISTRIBUTION O valor é uma distribuição [Distribution][google.api.Distribution].
MONEY O valor é em dinheiro.

MetricRule

Vincula métodos da API a métricas. Vincular um método a uma métrica faz com que os comportamentos de cota configurados para a métrica se apliquem ao método de chamada.

Campos
selector

string

Seleciona os métodos aos quais esta regra se aplica.

Consulte o selector para detalhes da sintaxe.

metric_costs

map<string, int64>

Métricas a serem atualizadas quando os métodos selecionados são chamados e o custo associado aplicado a cada métrica.

A chave do mapa é o nome da métrica, e os valores são a quantidade aumentada para a métrica contra a qual os limites da cota são definidos. O valor não pode ser negativo.

Page

Representa uma página da documentação. Uma página pode conter subpáginas para representar uma estrutura de conjunto de documentação aninhada.

Campos
name

string

O nome da página. Ele será usado como identificador da página para gerar o URI da página, o texto do link para esta página na navegação etc. O nome completo da página (a partir do nome da página raiz para esta página, concatenado com .) pode ser usado como referência para a página na sua documentação. Exemplo:


pages:
- name: Tutorial
  content: (== include tutorial.md ==)
  subpages:
  - name: Java
    content: (== include tutorial_java.md ==)

Você pode fazer referência à página Java por meio da sintaxe do link de referência do Markdown: [Java][Tutorial.Java].

content

string

O conteúdo do Markdown da página. Você pode usar

(== include {path} ==)

para incluir conteúdo de um arquivo do Markdown.

subpages[]

Page

Subpáginas desta página. A ordem das subpáginas especificadas aqui será herdada no docset gerado.

Quota

A configuração da cota ajuda a conseguir imparcialidade e criar orçamentos no Service Usage.

A configuração da cota funciona da seguinte maneira: - A configuração do serviço define um conjunto de métricas. - Para chamadas da API, quota.metric_rules mapeia métodos para métricas com os custos correspondentes. - quota.limits define limites para as métricas, que serão usados para verificações de cota no tempo de execução.

Um exemplo de configuração de cota no formato yaml:

Cota:

 - name: apiWriteQpsPerProject
   metric: library.googleapis.com/write_calls
   unit: "1/min/{project}"  # rate limit for consumer projects
   values:
     STANDARD: 10000

 # The metric rules bind all methods to the read_calls metric,
 # except for the UpdateBook and DeleteBook methods. These two methods
 # are mapped to the write_calls metric, with the UpdateBook method
 # consuming at twice rate as the DeleteBook method.
 metric_rules:
 - selector: "*"
   metric_costs:
     library.googleapis.com/read_calls: 1
 - selector: google.example.library.v1.LibraryService.UpdateBook
   metric_costs:
     library.googleapis.com/write_calls: 2
 - selector: google.example.library.v1.LibraryService.DeleteBook
   metric_costs:
     library.googleapis.com/write_calls: 1

Definição da métrica correspondente:

 metrics:
 - name: library.googleapis.com/read_calls
   display_name: Read requests
   metric_kind: DELTA
   value_type: INT64

 - name: library.googleapis.com/write_calls
   display_name: Write requests
   metric_kind: DELTA
   value_type: INT64
Campos
limits[]

QuotaLimit

Lista de definições de QuotaLimit para o serviço.

metric_rules[]

MetricRule

Lista de definições de MetricRule. Cada uma mapeia um método selecionado para uma ou mais métricas.

QuotaLimit

QuotaLimit define um limite específico que se aplica em uma duração específica para um tipo de limite. Pode haver no máximo um limite para uma duração e combinação de tipo de limite definida dentro de um QuotaGroup.

Campos
name

string

Nome do limite da cota.

O nome precisa ser fornecido e ser exclusivo no serviço. O nome só pode incluir caracteres alfanuméricos e "-".

O comprimento máximo do nome do limite é de 64 caracteres.

description

string

Opcional. Descrição detalhada e visível pelo usuário para esse limite de cota. Deve ser usado apenas quando, para entender esse limite, for necessário mais contexto do que o fornecido pelo nome de exibição do limite (consulte display_name).

metric

string

O nome da métrica a que este limite de cota se aplica. Os limites de cota com a mesma métrica serão verificados juntos durante o tempo de execução. A métrica precisa ser definida dentro da configuração do serviço.

unit

string

Especifique a unidade do limite da cota. Usa a mesma sintaxe que [Metric.unity][]. Os tipos de unidades aceitas são determinados pelo sistema de back-end de cota.

Veja alguns exemplos: * "1/min./{project}" para a cota por minuto por projeto.

Observação: a ordem dos componentes da unidade é insignificante. O "1" no início é obrigatório para seguir a sintaxe da unidade da métrica.

values

map<string, int64>

Valores-limite nivelados. Você precisa especificar esse campo como um par de chave-valor, com um número inteiro que é o número máximo de solicitações permitidas para a unidade especificada. Atualmente, apenas STANDARD é aceito.

Service

Service é o objeto raiz do esquema de configuração de serviços do Google. Ele descreve as informações básicas de um serviço, como nome e título, e delega outros aspectos a subseções. Cada subseção é uma mensagem proto ou uma mensagem proto repetida que configura um aspecto específico, como auth. Veja a definição de cada mensagem proto para saber mais detalhes.

Exemplo:

type: google.api.Service
config_version: 3
name: calendar.googleapis.com
title: Google Calendar API
apis:
- name: google.calendar.v3.Calendar
authentication:
  providers:
  - id: google_calendar_auth
    jwks_uri: https://www.googleapis.com/oauth2/v1/certs
    issuer: https://securetoken.google.com
  rules:
  - selector: "*"
    requirements:
      provider_id: google_calendar_auth
Campos
config_version

UInt32Value

A versão semântica da configuração do serviço. A versão de configuração afeta a interpretação da configuração do serviço. Por exemplo, alguns recursos são ativados por padrão para determinadas versões de configuração. A versão de configuração mais recente é 3 .

name

string

O endereço DNS no qual este serviço está disponível. Por exemplo, calendar.googleapis.com.

id

string

Um ID exclusivo para uma instância específica dessa mensagem, geralmente atribuída pelo cliente para fins de rastreamento. Se estiver vazio, o servidor pode optar por gerar um ID.

title

string

O título do produto para este serviço.

apis[]

Api

Uma lista de interfaces da API exportadas por este serviço. Apenas o campo name da google.protobuf.Api precisa ser fornecido pelo autor da configuração porque os campos restantes serão derivados do IDL durante o processo de normalização. Você verá um erro se especificar uma interface de API que não possa ser resolvida nos arquivos IDL associados.

types[]

Type

Uma lista de todos os tipos de mensagem proto incluídos neste serviço de API. Tipos referenciados direta ou indiretamente pelas apis são incluídos automaticamente. Mensagens que não são referenciadas, mas que devem ser incluídas, como tipos usados pelo google.protobuf.Any precisam ser nominalmente listadas aqui. Exemplo:


types:
- name: google.protobuf.Int32

enums[]

Enum

Uma lista de todos os tipos de enum incluídos neste serviço de API. Enums referenciados direta ou indiretamente pelas apis são incluídos automaticamente. Enums que não são referenciados, mas que devem ser incluídos, precisam ser nominalmente listados aqui. Exemplo:


enums:
- name: google.someapi.v1.SomeEnum

http

Http

Configuração de HTTP.

quota

Quota

Configuração de cota.

authentication

Authentication

Configuração de autenticação.

usage

Usage

Configuração que controla o uso desse serviço.

endpoints[]

Endpoint

Configuração para pontos de extremidade da rede. Se estiver vazio, um endpoint com o mesmo nome do serviço será gerado automaticamente para atender a todas as APIs definidas.

metrics[]

MetricDescriptor

Define as métricas usadas por este serviço.

system_parameters

SystemParameters

Configuração de parâmetros do sistema.

Parâmetros do sistema

Defina o nome e a localização de um parâmetro. O parâmetro pode ser passado como um cabeçalho HTTP ou como parâmetro de consulta do URL. Se ambos forem transmitidos, o comportamento dependerá da implementação.

Campos
name

string

Defina o nome do parâmetro, por exemplo, "api_key". Ele diferencia maiúsculas de minúsculas.

http_header

string

Defina o nome do cabeçalho HTTP que será usado para o parâmetro. Não diferencia maiúsculas e minúsculas.

url_query_parameter

string

Defina o nome do parâmetro de consulta do URL que será usado para o parâmetro. Ele diferencia maiúsculas de minúsculas.

SystemParameterRule

Define uma regra que mapeará as definições do sistema de parâmetros para métodos.

Campos
selector

string

Seleciona os métodos aos quais esta regra se aplica. Use "*" para indicar todos os métodos em todas as APIs.

Consulte o selector para detalhes da sintaxe.

parameters[]

SystemParameter

Define parâmetros. É possível definir vários nomes para um parâmetro. Para uma determinada chamada de método, use apenas um deles. Se vários nomes forem usados, o comportamento dependerá da implementação. Se nenhum dos nomes especificados estiver presente, o comportamento dependerá do parâmetro.

SystemParameters

Configuração de parâmetros do sistema

Um parâmetro do sistema é um tipo especial de parâmetro definido pelo sistema da API, não por uma API individual. Normalmente, ele é mapeado para um cabeçalho HTTP e/ou um parâmetro de consulta do URL. A configuração a seguir especifica quais métodos alteram os nomes dos parâmetros do sistema.

Campos
rules[]

SystemParameterRule

Defina os parâmetros do sistema.

Os parâmetros definidos neste momento substituirão os parâmetros padrão implementados pelo sistema. Se este campo estiver faltando na configuração do serviço, os parâmetros padrão do sistema serão usados. Parâmetros e nomes padrão do sistema dependem da implementação.

Exemplo: define a chave de API para todos os métodos


system_parameters
  rules:
    - selector: "*"
      parameters:
        - name: api_key
          url_query_parameter: api_key

Exemplo: defina dois nomes de chaves de API para um método específico.


system_parameters
  rules:
    - selector: "/ListShelves"
      parameters:
        - name: api_key
          http_header: Api-Key1
        - name: api_key
          http_header: Api-Key2

OBSERVAÇÃO: todas as regras de configuração do serviço seguem a ordem "vale a última opção".

Usage

Configuração que controla o uso de um serviço.

Campos
rules[]

UsageRule

Uma lista de regras de uso que se aplicam aos métodos individuais da API.

OBSERVAÇÃO: todas as regras de configuração do serviço seguem a ordem "vale a última opção".

UsageRule

Regras de configuração de uso para o serviço.

OBSERVAÇÃO: em desenvolvimento.

Use esta regra para configurar chamadas não registradas para o serviço. Chamadas não registradas são chamadas que não contêm a identificação do projeto de consumidor. Exemplo: chamadas que não contêm uma chave da API. Por padrão, os métodos da API não permitem chamadas não registradas e cada chamada de método precisa ser identificada por uma identidade de projeto de consumidor. Use esta regra para permitir/bloquear chamadas não registradas.

Exemplo de uma API que quer permitir chamadas não registradas para todo o serviço.

usage:
  rules:
  - selector: "*"
    allow_unregistered_calls: true

Exemplo de um método que quer permitir chamadas não registradas.

usage:
  rules:
  - selector: "google.example.library.v1.LibraryService.CreateBook"
    allow_unregistered_calls: true
Campos
selector

string

Seleciona os métodos aos quais esta regra se aplica. Use "*" para indicar todos os métodos em todas as APIs.

Consulte o selector para detalhes da sintaxe.

allow_unregistered_calls

bool

Se for "True", o método selecionado permite chamadas não registradas. Por exemplo, chamadas que não identificam nenhum usuário ou aplicativo.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.