Api

Api é um descritor leve para uma interface da API.

As interfaces também são descritas como "serviços de buffer de protocolo" em alguns contextos, como na palavra-chave "serviço" em um arquivo .proto, mas são diferentes dos serviços da API, que representam uma implementação concreta de uma interface em oposição a uma simples descrição de métodos e ligações. Elas também podem ser simplesmente chamadas de "APIs" em outros contextos, como o nome desta mensagem. Consulte https://cloud.google.com/apis/design/glossary para ver a terminologia detalhada.

Representação JSON

{
  "name": string,
  "methods": [
    {
      object(Method)
    }
  ],
  "options": [
    {
      object(Option)
    }
  ],
  "version": string,
  "sourceContext": {
    object(SourceContext)
  },
  "mixins": [
    {
      object(Mixin)
    }
  ],
  "syntax": enum(Syntax)
}
Campos
name

string

O nome totalmente qualificado desta interface, inclusive o nome do pacote seguido do nome simples da interface.

methods[]

object(Method)

Os métodos desta interface, em ordem não especificada.

options[]

object(Option)

Quaisquer metadados anexados à interface.

version

string

Uma string de versão para esta interface. Se especificada, precisa ter o formato major-version.minor-version , como em 1.10. Se a versão secundária for omitida, o valor padrão é zero. Se o campo da versão inteira estiver em branco, a versão principal é derivada do nome do pacote, conforme descrito abaixo. Se o campo não estiver em branco, a versão no nome do pacote será verificada para ser consistente com o que é fornecido aqui.

O esquema de versão usa o controle de versão semântico em que o número da versão principal indica uma alteração importante e a versão secundária indica uma alteração adicional e não importante. Ambos os números de versão são sinais para os usuários sobre que esperar de diferentes versões e precisam ser cuidadosamente escolhidos de acordo com o plano do produto.

A versão principal também se reflete no nome do pacote da interface, que precisa terminar em v<major-version>, como em google.feature.v1. Nas versões principais 0 e 1, o sufixo pode ser omitido. As versões principais zero só devem ser usadas para interfaces experimentais, não em interfaces com ampla disponibilidade.

sourceContext

object(SourceContext)

Contexto de origem para o serviço de buffer de protocolo representado por esta mensagem.

mixins[]

object(Mixin)

Interfaces incluídas. Veja Mixin.

syntax

enum(Syntax)

A sintaxe de origem do serviço.

Método

Representa um método de uma interface da API.

Representação JSON

{
  "name": string,
  "requestTypeUrl": string,
  "requestStreaming": boolean,
  "responseTypeUrl": string,
  "responseStreaming": boolean,
  "options": [
    {
      object(Option)
    }
  ],
  "syntax": enum(Syntax)
}
Campos
name

string

O nome simples deste método.

requestTypeUrl

string

Um URL do tipo de mensagem de entrada.

requestStreaming

boolean

Se for "True", a solicitação será transmitida.

responseTypeUrl

string

O URL do tipo de mensagem de saída.

responseStreaming

boolean

Se for "True", a resposta será transmitida.

options[]

object(Option)

Quaisquer metadados anexados ao método.

syntax

enum(Syntax)

A sintaxe de origem desse método.

Opção

Uma opção de buffer de protocolo, que pode ser anexada a uma mensagem, campo, enumeração etc.

Representação JSON

{
  "name": string,
  "value": {
    "@type": string,
    field1: ...,
    ...
  }
}
Campos
name

string

O nome da opção. Para opções integradas do protobuf (opções definidas em descriptor.proto), este é o nome curto. Por exemplo, "mapEntry". Para opções personalizadas, precisa ser o nome totalmente qualificado. Por exemplo, "google.api.http".

value

object

O valor da opção empacotado em qualquer mensagem. Se o valor for primitivo, o tipo de wrapper correspondente definido em google/protobuf/wrappers.proto precisa ser usado. Se o valor for um enum, ele precisa ser armazenado como um valor int32 por meio do tipo google.protobuf.Int32Value.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém um URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

SourceContext

SourceContext representa informações sobre a origem de um elemento protobuf, como o arquivo em que ele está definido.

Representação JSON

{
  "fileName": string
}
Campos
fileName

string

O nome qualificado do caminho do arquivo .proto que continha o elemento protobuf associado. Por exemplo: "google/protobuf/sourceContext.proto".

Mixin

Declara uma interface da API a ser incluída nesta interface. A interface que faz a inclusão precisa declarar novamente todos os métodos da interface inclusa, mas a documentação e as opções são herdadas da seguinte maneira:

  • Se, após o comentário e a remoção de espaços em branco, a string de documentação do método redeclarado estiver em branco, ela será herdada do método original.

  • Cada anotação pertencente à configuração do serviço (http, visibilidade) que não está configurada no método redeclarado será herdada.

  • Se uma anotação http for herdada, o padrão de caminho será modificado da seguinte maneira. Qualquer prefixo de versão será substituído pela versão da interface que fez a inclusão mais o caminho root, se especificado.

Exemplo de mixin simples:

package google.acl.v1;
service AccessControl {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v1/{resource=**}:getAcl";
  }
}

package google.storage.v2;
service Storage {
  //       rpc GetAcl(GetAclRequest) returns (Acl);

  // Get a data record.
  rpc GetData(GetDataRequest) returns (Data) {
    option (google.api.http).get = "/v2/{resource=**}";
  }
}

Exemplo de configuração de mixin:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl

A construção do mixin implica que todos os métodos em AccessControl também são declarados com o mesmo nome e tipos de solicitação/resposta em Storage. Um gerador de documentação ou um processador de anotações verá o método Storage.GetAcl efetivo após herdar a documentação e as anotações da seguinte maneira:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/{resource=**}:getAcl";
  }
  ...
}

Observe como a versão no padrão de caminho mudou de v1 para v2.

Se o campo root no mixin for especificado, ele precisa ser um caminho relativo em que os caminhos HTTP herdados são colocados. Por exemplo:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl
    root: acls

Isso implica a seguinte anotação HTTP herdada:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}
Representação JSON

{
  "name": string,
  "root": string
}
Campos
name

string

O nome totalmente qualificado da interface em que está incluído.

root

string

Se não estiver em branco, especifica um caminho em que os caminhos HTTP herdados têm acesso root.