Method: projects.locations.endpoints.queryData

Esegue query sulla rete per ottenere informazioni memorizzate nel ledger, come account e transazioni.

L'accesso a determinati campi sensibili, come i saldi degli account, potrebbe essere limitato in base all'identità del mittente derivata dalla firma nella richiesta. Se il mittente non dispone dell'autorizzazione, i campi sensibili verranno oscurati dalla risposta e segnalati nel campo redactedFields.

Richiesta HTTP


POST https://universalledger.googleapis.com/v1/{endpoint=projects/*/locations/*/endpoints/*}:queryData

Gli URL utilizzano la sintassi di transcodifica gRPC.

Parametri di percorso

Parametri
endpoint

string

Obbligatorio. L'endpoint per gestire la richiesta. Formato: projects/{project}/locations/{location}/endpoints/{endpoint} La località è una regione.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "serializedSignedQueryRequest": string
}
Campi
serializedSignedQueryRequest

string (bytes format)

Obbligatorio. Un SignedQueryRequest serializzato protobuf per eseguire query sulla rete Universal Ledger.

Una stringa con codifica in base64.

Corpo della risposta

Messaggio di risposta per endpoints.queryData.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "redactedFields": [
    {
      object (RedactedField)
    }
  ],

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "account": {
    object (Account)
  },
  "transactionState": {
    object (TransactionState)
  }
  // End of mutually exclusive fields.
}
Campi
redactedFields[]

object (RedactedField)

Indica quali campi sono stati oscurati nella risposta a causa di limitazioni delle autorizzazioni.
Il risultato specifico della query. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
account

object (Account)

I dati dell'account, se la query riguardava un account.
transactionState

object (TransactionState)

Lo stato di una transazione, se la query riguardava una transazione.
Fine dei campi che si escludono a vicenda.

Ambiti di autorizzazione

Richiede il seguente ambito OAuth:

  • https://www.googleapis.com/auth/cloud-platform

Per saperne di più, consulta la Authentication Overview.

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa endpoint:

  • universalledger.endpoints.readNetwork

Per saperne di più, consulta la documentazione di IAM.

TransactionState

Lo stato di una transazione.

Rappresentazione JSON 
{
  "transactionAttempts": [
    {
      object (TransactionAttempt)
    }
  ]
}
Campi
transactionAttempts[]

object (TransactionAttempt)

Una voce per ogni invio noto della transazione al validator che gestisce la richiesta.

RedactedField

Informazioni su un campo oscurato nella risposta.

Rappresentazione JSON 
{
  "redactedPath": string,
  "reason": string,
  "reasonCode": enum (Code)
}
Campi
redactedPath

string (FieldMask format)

Solo output. I percorsi dei campi completi che sono stati oscurati dal payload.

Si tratta di un elenco separato da virgole di nomi completi dei campi. Esempio: "user.displayName,photo".
reason

string

Solo output. Una spiegazione leggibile del motivo per cui i campi sono stati oscurati.
reasonCode

enum (Code)

Solo output. Un codice leggibile da macchina che indica il motivo per cui i campi sono stati oscurati.

Codice

I codici di errore canonici per le API gRPC.

A volte possono essere applicati più codici di errore. I servizi devono restituire il codice di errore più specifico applicabile. Ad esempio, preferisci OUT_OF_RANGE a FAILED_PRECONDITION se si applicano entrambi i codici. Analogamente, preferisci NOT_FOUND o ALREADY_EXISTS rispetto a FAILED_PRECONDITION.

Enum
OK

Non è un errore; viene restituito in caso di esito positivo.

Mappatura HTTP: 200 OK
CANCELLED

L'operazione è stata annullata, in genere dal chiamante.

Mappatura HTTP: 499 Client Closed Request
UNKNOWN

Errore sconosciuto. Ad esempio, questo errore può essere restituito quando un valore Status ricevuto da un altro spazio di indirizzi appartiene a uno spazio di errore non noto in questo spazio di indirizzi. Anche gli errori generati dalle API che non restituiscono informazioni sufficienti sull'errore possono essere convertiti in questo errore.

Mappatura HTTP: 500 Errore interno del server
INVALID_ARGUMENT

Il client ha specificato un argomento non valido. Tieni presente che questo valore è diverso da FAILED_PRECONDITION. INVALID_ARGUMENT indica argomenti problematici indipendentemente dallo stato del sistema (ad esempio, un nome file non valido).

Mappatura HTTP: 400 Bad Request
DEADLINE_EXCEEDED

La scadenza è trascorsa prima che l'operazione potesse essere completata. Per le operazioni che modificano lo stato del sistema, questo errore potrebbe essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta corretta da un server potrebbe essere stata ritardata abbastanza da far scadere la scadenza.

Mappatura HTTP: 504 Gateway Timeout
NOT_FOUND

Impossibile trovare un'entità richiesta (ad es. file o directory).

Nota per gli sviluppatori di server: se una richiesta viene rifiutata per un'intera classe di utenti, ad esempio per l'implementazione graduale di una funzionalità o per una lista consentita non documentata, è possibile utilizzare NOT_FOUND. Se una richiesta viene rifiutata per alcuni utenti all'interno di una classe di utenti, ad esempio controllo dell'accesso basato sugli utenti, è necessario utilizzare PERMISSION_DENIED.

Mappatura HTTP: 404 - Non trovato
ALREADY_EXISTS

L'entità che un client ha tentato di creare (ad es. file o directory) esiste già.

Mappatura HTTP: 409 Conflict
PERMISSION_DENIED

Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata. PERMISSION_DENIED non deve essere utilizzato per i rifiuti causati dall'esaurimento di una risorsa (per questi errori utilizza invece RESOURCE_EXHAUSTED). PERMISSION_DENIED non deve essere utilizzato se il chiamante non può essere identificato (per questi errori utilizza UNAUTHENTICATED). Questo codice di errore non implica che la richiesta sia valida o che l'entità richiesta esista o soddisfi altre precondizioni.

Mappatura HTTP: 403 Forbidden
UNAUTHENTICATED

La richiesta non ha credenziali di autenticazione valide per l'operazione.

Mappatura HTTP: 401 Unauthorized
RESOURCE_EXHAUSTED

Alcune risorse sono state esaurite, ad esempio una quota per utente, o forse l'intero file system ha esaurito lo spazio.

Mappatura HTTP: 429 Too Many Requests
FAILED_PRECONDITION

L'operazione è stata rifiutata perché il sistema non si trova in uno stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota, un'operazione rmdir viene applicata a una non directory e così via.

Gli implementatori dei servizi possono utilizzare le seguenti linee guida per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE: (a) Utilizza UNAVAILABLE se il client può riprovare solo la chiamata non riuscita. (b) Utilizza ABORTED se il client deve riprovare a un livello superiore. Ad esempio, quando un test-and-set specificato dal client non va a buon fine, indicando che il client deve riavviare una sequenza di lettura-modifica-scrittura. (c) Utilizza FAILED_PRECONDITION se il client non deve riprovare finché lo stato del sistema non è stato esplicitamente corretto. Ad esempio, se un comando "rmdir" non va a buon fine perché la directory non è vuota, deve essere restituito FAILED_PRECONDITION, poiché il client non deve riprovare a meno che i file non vengano eliminati dalla directory.

Mappatura HTTP: 400 Bad Request
ABORTED

L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un errore di controllo del sequencer o un'interruzione della transazione.

Consulta le linee guida riportate sopra per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE.

Mappatura HTTP: 409 Conflict
OUT_OF_RANGE

È stato eseguito un tentativo di operazione oltre l'intervallo valido. Ad esempio, ricerca o lettura oltre la fine del file.

A differenza di INVALID_ARGUMENT, questo errore indica un problema che potrebbe essere risolto se lo stato del sistema cambia. Ad esempio, un file system a 32 bit genererà INVALID_ARGUMENT se viene richiesto di leggere un offset non compreso nell'intervallo [0,2^32-1], ma genererà OUT_OF_RANGE se viene richiesto di leggere un offset oltre le dimensioni attuali del file.

C'è una discreta sovrapposizione tra FAILED_PRECONDITION e OUT_OF_RANGE. Ti consigliamo di utilizzare OUT_OF_RANGE (l'errore più specifico) quando applicabile, in modo che i chiamanti che eseguono l'iterazione in uno spazio possano cercare facilmente un errore OUT_OF_RANGE per rilevare quando hanno finito.

Mappatura HTTP: 400 Bad Request
UNIMPLEMENTED

L'operazione non è implementata o non è supportata/abilitata in questo servizio.

Mappatura HTTP: 501 Not Implemented
INTERNAL

Errori interni. Ciò significa che alcune invarianti previste dal sistema sottostante sono state violate. Questo codice di errore è riservato a errori gravi.

Mappatura HTTP: 500 Errore interno del server
UNAVAILABLE

Il servizio non è attualmente disponibile. Molto probabilmente si tratta di una condizione temporanea, che può essere corretta riprovando con un backoff. Tieni presente che non è sempre sicuro riprovare le operazioni non idempotenti.

Consulta le linee guida riportate sopra per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE.

Mappatura HTTP: 503 Service Unavailable
DATA_LOSS

Perdita o danneggiamento dei dati non recuperabili.

Mappatura HTTP: 500 Errore interno del server