Index
AuthProvider(mensagem)AuthRequirement(mensagem)Authentication(mensagem)AuthenticationRule(mensagem)CustomHttpPattern(mensagem)Documentation(mensagem)DocumentationRule(mensagem)Endpoint(mensagem)Http(mensagem)HttpRule(mensagem)LabelDescriptor(mensagem)LabelDescriptor.ValueType(enum)MetricDescriptor(mensagem)MetricDescriptor.MetricKind(enum)MetricDescriptor.ValueType(enum)MetricRule(mensagem)Page(mensagem)Quota(mensagem)QuotaLimit(mensagem)Service(mensagem)SystemParameter(mensagem)SystemParameterRule(mensagem)SystemParameters(mensagem)Usage(mensagem)UsageRule(mensagem)
AuthProvider
Configuração para um provedor de autenticação, inclusive suporte a JSON Web Token (JWT).
| Campos | |
|---|---|
id |
O identificador exclusivo do provedor de autenticação. Será referenciado por Exemplo: "bookstore_auth". |
issuer |
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: Exemplo: |
jwks_uri |
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). |
audiences |
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:// Exemplo:
|
authorization_url |
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 |
Exemplo:
|
audiences |
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:// Exemplo:
|
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[] |
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[] |
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 |
Seleciona os métodos aos quais esta regra se aplica. Consulte o |
requirements[] |
Requisitos para provedores de autenticação adicionais. |
CustomHttpPattern
Para definir o verbo HTTP personalizado, usa-se um padrão personalizado.
| Campos | |
|---|---|
kind |
O nome desse verbo HTTP personalizado. |
path |
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 |
Um breve resumo do que o serviço faz. Só pode ser fornecido por texto simples. |
pages[] |
As páginas de nível superior do conjunto de documentação. |
rules[] |
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 |
O URL para a raiz da documentação. |
overview |
Declara uma única página de visão geral. Exemplo:
Este é um atalho para a seguinte declaração (usando estilo de páginas):
Observação: não é possível especificar os campos |
DocumentationRule
Uma regra de documentação que fornece informações sobre elementos individuais da API.
| Campos | |
|---|---|
selector |
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 |
Descrição das APIs selecionadas. |
deprecation_description |
Descrição de suspensão do uso dos elementos selecionados. Pode ser fornecida se um elemento for marcado como |
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 |
O nome canônico desse ponto de extremidade. |
allow_cors |
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[] |
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 |
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¶m=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:
- O campo
bodyespecifica*, um caminho de campo ou é omitido. Se omitido, indica que não há corpo de solicitação HTTP. - 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. - Os parâmetros de consulta de URL encontrados na solicitação HTTP são mapeados para os campos (c).
- 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 |
Seleciona os métodos aos quais esta regra se aplica. Consulte o |
|
body |
O nome do campo de solicitação cujo valor é mapeado para o corpo HTTP ou |
|
additional_bindings[] |
Outras vinculações HTTP para o seletor. As vinculações aninhadas não podem conter um campo |
|
rest_collection |
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:
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_method_name |
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:
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 |
Usado para listar e receber informações sobre recursos. |
|
put |
Usado para atualizar um recurso. |
|
post |
Usado para criar um recurso. |
|
delete |
Usado para excluir um recurso. |
|
patch |
Usado para atualizar um recurso. |
|
custom |
O padrão personalizado é usado para especificar um método HTTP que não está incluído no campo |
|
LabelDescriptor
Descrição de um rótulo.
| Campos | |
|---|---|
key |
A chave de rótulo |
value_type |
O tipo de dados que pode ser atribuído ao rótulo. |
description |
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 |
O nome do recurso do descritor de métrica. |
type |
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
|
labels[] |
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 |
metric_kind |
Indica se a métrica registra valores instantâneos, alterações em um valor, etc. Algumas combinações de |
value_type |
Indica se a medida é um número inteiro, um número de ponto flutuante, etc. Algumas combinações de |
unit |
A unidade em que o valor da métrica é relatado. Aplicável apenas se o Unidades básicas (UNIT)
Prefixos (PREFIX)
Gramática A gramática inclui a unidade sem dimensão A gramática também inclui os seguintes conectores:
Veja abaixo a gramática de uma unidade:
Observações:
|
description |
Uma descrição detalhada da métrica, que pode ser usada na documentação. |
display_name |
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 |
Seleciona os métodos aos quais esta regra se aplica. Consulte o |
metric_costs |
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 |
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
Você pode fazer referência à página |
content |
O conteúdo do Markdown da página. Você pode usar
para incluir conteúdo de um arquivo do Markdown. |
subpages[] |
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[] |
Lista de definições de |
metric_rules[] |
Lista de definições de |
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 |
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 |
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 |
metric |
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 |
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 |
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 |
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 é |
name |
O endereço DNS no qual este serviço está disponível. Por exemplo, |
id |
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 |
O título do produto para este serviço. |
apis[] |
Uma lista de interfaces da API exportadas por este serviço. Apenas o campo |
types[] |
Uma lista de todos os tipos de mensagem proto incluídos neste serviço de API. Tipos referenciados direta ou indiretamente pelas
|
enums[] |
Uma lista de todos os tipos de enum incluídos neste serviço de API. Enums referenciados direta ou indiretamente pelas
|
http |
Configuração de HTTP. |
quota |
Configuração de cota. |
authentication |
Configuração de autenticação. |
usage |
Configuração que controla o uso desse serviço. |
endpoints[] |
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[] |
Define as métricas usadas por este serviço. |
system_parameters |
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 |
Defina o nome do parâmetro, por exemplo, "api_key". Ele diferencia maiúsculas de minúsculas. |
http_header |
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 |
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 |
Seleciona os métodos aos quais esta regra se aplica. Use "*" para indicar todos os métodos em todas as APIs. Consulte o |
parameters[] |
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[] |
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
Exemplo: defina dois nomes de chaves de API para um método específico.
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[] |
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 |
Seleciona os métodos aos quais esta regra se aplica. Use "*" para indicar todos os métodos em todas as APIs. Consulte o |
allow_unregistered_calls |
Se for "True", o método selecionado permite chamadas não registradas. Por exemplo, chamadas que não identificam nenhum usuário ou aplicativo. |