Operação

Este recurso representa uma operação de longa duração resultante de uma chamada à API de rede.

Representação JSON 

{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Campos
name

string

O nome atribuído pelo servidor, que é exclusivo somente no mesmo serviço que o retorna originalmente. Quando você usa o mapeamento HTTP padrão, o name tem o formato operations/some/unique/name.

metadata

object

Metadados específicos do serviço associados à operação. Eles geralmente contêm informações sobre o progresso e metadados comuns como a hora da criação. Em alguns serviços, esses metadados talvez não sejam fornecidos. Em qualquer método que retorna uma operação de longa duração, o tipo de metadados é documentado, se houver.

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" }.
done

boolean

Se o valor é false, isso significa que a operação continua em andamento. Se for true, a operação já foi concluída, e error ou response estão disponíveis.

Campo de união result. O resultado da operação, que pode ser um error ou uma response válida. Se done == false, nem error nem response é definido. Se done == true, exatamente um error ou response é definido. O result será somente um dos seguintes:
error

object(Status)

O resultado do erro da operação em caso de falha ou cancelamento.

response

object

A resposta normal da operação, em caso de êxito. Se o método original não retornar dados em caso de sucesso, como Delete, a resposta será google.protobuf.Empty. Quando esse método é um Get/Create/Update padrão, a resposta é o recurso. Em outros métodos, ela é do tipo XxxResponse, onde Xxx é o nome do método original. Por exemplo, se o nome do método é TakeSnapshot(), o tipo de resposta deduzido é TakeSnapshotResponse.

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" }.

Status

O tipo de Status define um modelo de erro lógico compatível com diversos ambientes de programação, incluindo as APIs REST e RPC, e é usado pelo gRPC. O modelo de erro foi desenvolvido para ser:

  • simples de usar e entender para a maioria dos usuários;
  • flexível o suficiente para atender às necessidades imprevistas.

Visão geral

A mensagem de Status contém três partes de dados: código do erro, mensagem de erro e detalhes do erro. O código do erro precisa ser um valor de enum google.rpc.Code, mas outros códigos de erro poderão ser aceitos, se necessário. A mensagem de erro é uma mensagem em inglês que ajuda o desenvolvedor a entender e resolver o erro. Se uma mensagem de erro localizada para o usuário for necessária, coloque-a nos detalhes do erro ou faça a localização no cliente. Os detalhes opcionais do erro podem conter informações arbitrárias sobre ele. Há um conjunto predefinido de tipos de detalhes de erro no pacote google.rpc para as condições de erros comuns.

Mapeamento de linguagem

A mensagem de Status é a representação lógica do modelo de erro, mas não está necessariamente no formato de transmissão real. Quando essa mensagem de Status é exposta em diferentes bibliotecas de cliente e protocolos de transmissão, ela pode ser mapeada de modo diferente. Por exemplo, talvez ela seja mapeada para algumas exceções em Java, mas com probabilidade maior para alguns códigos de erro em C.

Outros usos

O modelo de erro e a mensagem de Status podem ser usados em diversos ambientes, com ou sem APIs, para que o desenvolvedor tenha uma experiência consistente, independentemente do ambiente usado.

Os exemplos de uso desse modelo de erro incluem:

  • erros parciais. Para que os erros parciais de um serviço sejam retornados ao cliente, incorpore o Status na resposta normal para indicar os erros parciais.

  • erros de fluxo de trabalho. Um fluxo de trabalho típico tem várias etapas. Cada etapa pode ter uma mensagem de Status para relatar o erro.

  • operações em lote. Se um cliente usa solicitação em lote e resposta em lote, use a mensagem de Status diretamente dentro da resposta em lote, uma para cada sub-resposta de erro.

  • operações assíncronas. Quando uma chamada à API incorpora resultados de operação assíncrona, o status dessas operações precisa ser representado diretamente usando a mensagem de Status.

  • registros. Quando alguns erros de API são armazenados em registros, a mensagem de Status pode ser usada diretamente após qualquer remoção necessária por motivos de segurança/privacidade.

Representação JSON 

{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

number

Código de status, que precisa ser um valor de enum google.rpc.Code.

message

string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro direcionada ao usuário precisa ser localizada e enviada no campo google.rpc.Status.details ou localizada pelo cliente.

details[]

object

Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem.

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" }.