Operation

Questa risorsa rappresenta un'operazione a lunga esecuzione che è il risultato di una chiamata all'API di rete.

Rappresentazione 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.
}
Campi
name

string

Il nome assegnato dal server, che è univoco solo all'interno dello stesso servizio che lo restituisce originariamente. Se utilizzi la mappatura HTTP predefinita, name deve essere un nome di risorsa che termina con operations/{unique_id}.

metadata

object

Metadati specifici del servizio associati all'operazione. In genere contiene informazioni sull'avanzamento e metadati comuni come l'ora di creazione. Alcuni servizi potrebbero non fornire questi metadati. Qualsiasi metodo che restituisce un'operazione di lunga durata deve documentare il tipo di metadati, se presente.

Un oggetto contenente campi di tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.
done

boolean

Se il valore è false, significa che l'operazione è ancora in corso. Se true, l'operazione è completata e error o response è disponibile.

Campo unione result. Il risultato dell'operazione, che può essere un error o un response valido. Se done == false, non è impostato né error né response. Se done == true, è impostato esattamente uno tra error o response. result può essere solo uno dei seguenti:
error

object (Status)

Il risultato dell'errore dell'operazione in caso di fallimento o annullamento.

response

object

La risposta normale dell'operazione in caso di esito positivo. Se il metodo originale non restituisce dati in caso di esito positivo, ad esempio Delete, la risposta è google.protobuf.Empty. Se il metodo originale è standard Get/Create/Update, la risposta deve essere la risorsa. Per altri metodi, la risposta deve avere il tipo XxxResponse, dove Xxx è il nome del metodo originale. Ad esempio, se il nome del metodo originale è TakeSnapshot(), il tipo di risposta dedotto è TakeSnapshotResponse.

Un oggetto contenente campi di tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.

Stato

Il tipo Status definisce un modello di errore logico adatto a diversi ambienti di programmazione, tra cui API REST e API RPC. Viene utilizzato da gRPC. Il modello di errore è progettato per essere:

  • Semplice da usare e da comprendere per la maggior parte degli utenti
  • Abbastanza flessibile per soddisfare esigenze impreviste

Panoramica

Il messaggio Status contiene tre dati: codice errore, messaggio di errore e dettagli dell'errore. Il codice di errore deve essere un valore enum di google.rpc.Code, ma può accettare codici di errore aggiuntivi, se necessario. Il messaggio di errore deve essere un messaggio in inglese rivolto agli sviluppatori che li aiuti a comprendere e risolvere l'errore. Se è necessario un messaggio di errore localizzato per l'utente, inseriscilo nei dettagli dell'errore o localizzalo nel client. I dettagli facoltativi dell'errore possono contenere informazioni arbitrarie sull'errore. Nel pacchetto google.rpc è presente un insieme predefinito di tipi di dettagli degli errori che possono essere utilizzati per condizioni di errore comuni.

Mappatura delle lingue

Il messaggio Status è la rappresentazione logica del modello di errore, ma non è necessariamente il formato effettivo del cavo. Quando il messaggio Status è esposto in librerie client e protocolli di comunicazione diversi, può essere mappato in modo diverso. Ad esempio, è probabile che venga mappato ad alcune eccezioni in Java, ma è più probabile che venga mappato ad alcuni codici di errore in C.

Altri utilizzi

Il modello di errore e il messaggio Status possono essere utilizzati in vari ambienti, con o senza API, per fornire un'esperienza di sviluppo coerente in ambienti diversi.

Ecco alcuni esempi di utilizzo di questo modello di errore:

  • Errori parziali. Se un servizio deve restituire errori parziali al client, può incorporare Status nella risposta normale per indicarli.

  • Errori del flusso di lavoro. Un flusso di lavoro tipico prevede più passaggi. Ogni passaggio può avere un messaggio Status per la segnalazione degli errori.

  • Operazioni batch. Se un client utilizza la richiesta batch e la risposta batch, il messaggio Status deve essere utilizzato direttamente all'interno della risposta batch, una per ogni sottorisposta di errore.

  • Operazioni asincrone. Se una chiamata API incorpora i risultati delle operazioni asincrone nella risposta, lo stato di queste operazioni deve essere rappresentato direttamente utilizzando il messaggio Status.

  • Logging. Se alcuni errori dell'API vengono memorizzati nei log, il messaggio Status potrebbe essere utilizzato direttamente dopo lo stripping necessario per motivi di sicurezza/privacy.

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

number

Il codice di stato, che deve essere un valore enum di google.rpc.Code.

message

string

Un messaggio di errore rivolto agli sviluppatori, che deve essere in inglese. Qualsiasi messaggio di errore rivolto agli utenti deve essere localizzato e inviato nel campo google.rpc.Status.details o localizzato dal cliente.

details[]

object

Un elenco di messaggi che contengono i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi da utilizzare per le API.

Un oggetto contenente campi di tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.