Method: projects.locations.endpoints.queryData

查詢網路,取得儲存在帳本上的資訊,例如帳戶和交易。

系統可能會根據要求中簽章衍生的傳送者身分,限制存取某些機密欄位,例如帳戶餘額。如果寄件者沒有權限,系統會從回覆中遮蓋機密欄位,並在 redactedFields 欄位中回報。

HTTP 要求


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

這些網址使用 gRPC 轉碼語法。

路徑參數

參數
endpoint

string

這是必要旗標,提供要求的端點。格式:projects/{project}/locations/{location}/endpoints/{endpoint} 位置是區域。

要求主體

要求主體包含下列結構的資料:

JSON 表示法
{
  "serializedSignedQueryRequest": string
}
欄位
serializedSignedQueryRequest

string (bytes format)

這是必要旗標,用於查詢 Universal Ledger 網路的 protobuf 序列化 SignedQueryRequest。

Base64 編碼字串。

回應主體

endpoints.queryData 的回應訊息。

如果成功,回應主體會含有以下結構的資料:

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.
}
欄位
redactedFields[]

object (RedactedField)

指出因權限限制而從回應中遮蓋的欄位。

查詢專屬結果。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
account

object (Account)

如果查詢的是帳戶,則會顯示帳戶資訊。

transactionState

object (TransactionState)

交易狀態 (如果查詢的是交易)。

互斥欄位結束。

授權範圍

需要下列 OAuth 範圍:

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

詳情請參閱Authentication Overview。

IAM 權限

需要 endpoint 資源的下列 IAM 權限:

  • universalledger.endpoints.readNetwork

詳情請參閱 IAM 說明文件。

TransactionState

交易狀態。

JSON 表示法
{
  "transactionAttempts": [
    {
      object (TransactionAttempt)
    }
  ]
}
欄位
transactionAttempts[]

object (TransactionAttempt)

每筆交易提交至處理要求的驗證器時,都會產生一筆記錄。

RedactedField

回應中遮蓋欄位的相關資訊。

JSON 表示法
{
  "redactedPath": string,
  "reason": string,
  "reasonCode": enum (Code)
}
欄位
redactedPath

string (FieldMask format)

僅供輸出。從酬載中遮蓋的完整欄位路徑。

這是以半形逗號分隔的完整欄位名稱清單,範例:"user.displayName,photo"。

reason

string

僅供輸出。以人類可讀的方式說明欄位遮蓋原因。

reasonCode

enum (Code)

僅供輸出。機器可讀程式碼,說明欄位經過遮蓋的原因。

程式碼

gRPC API 的標準錯誤代碼。

有時可能適用多個錯誤代碼。服務應傳回最適用的特定錯誤代碼。例如,如果 OUT_OF_RANGE 與 FAILED_PRECONDITION 代碼都適用,則最好使用前者。同樣地,建議使用 NOT_FOUND 或 ALREADY_EXISTS,而非 FAILED_PRECONDITION。

列舉
OK

非錯誤;成功時傳回。

HTTP 對應:200 OK

CANCELLED

作業已取消,一般由呼叫者取消。

HTTP 對應:499 用戶端已關閉要求

UNKNOWN

發生不明錯誤,舉例來說,如果從其他位址空間收到的 Status 值屬於這個位址空間未知的錯誤空間,系統可能會傳回這項錯誤。由 API 發出但未傳回足夠錯誤資訊的錯誤也可能轉換為此錯誤。

HTTP 對應:500 內部伺服器錯誤

INVALID_ARGUMENT

用戶端指定了無效的引數。請注意,這與 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 表示無論系統狀態為何,引數都有問題 (例如檔案名稱格式錯誤)。

HTTP 對應:400 錯誤的要求

DEADLINE_EXCEEDED

期限於作業完成之前過期。針對變更系統狀態的作業,即使作業已成功完成,也可能傳回此錯誤。例如,來自伺服器的成功回應延遲時間可能已長到足以使期限過期。

HTTP 對應:504 閘道逾時

NOT_FOUND

找不到某些要求的實體 (例如檔案或目錄)。

伺服器開發人員注意事項:如果要求因整類使用者而遭拒,例如逐步推出功能或未記錄的許可清單,則可使用 NOT_FOUND。如果某類使用者 (例如使用者存取控管) 的部分使用者要求遭到拒絕,則必須使用 PERMISSION_DENIED。

HTTP 對應:404 找不到網頁

ALREADY_EXISTS

用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。

HTTP 對應:409 衝突

PERMISSION_DENIED

呼叫者沒有執行指定作業的權限。不得針對因耗用某些資源所導致的拒絕情形使用 PERMISSION_DENIED (請針對這些錯誤改用 RESOURCE_EXHAUSTED)。如果無法識別呼叫端,請勿使用 PERMISSION_DENIED (請改用 UNAUTHENTICATED 處理這類錯誤)。此錯誤代碼並不表示要求有效,或存在要求的實體,或滿足其他先決條件。

HTTP 對應:403 禁止

UNAUTHENTICATED

要求沒有作業的有效驗證憑證。

HTTP 對應:401 未授權

RESOURCE_EXHAUSTED

已耗盡某些資源,或許是每位使用者的配額,或許是完整檔案系統空間不足。

HTTP 對應:429 太多要求

FAILED_PRECONDITION

作業已遭拒絕,因為系統不在執行作業所需的狀態下。例如,要刪除的目錄還有內容、rmdir 作業套用至非目錄等。

服務實作者可參考下列指南,決定要使用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE:(a) 如果用戶端可以只重試失敗的呼叫,請使用 UNAVAILABLE。(b) 如果用戶端應在較高層級重試,請使用 ABORTED。例如,當用戶端指定的測試和設定失敗時,表示用戶端應重新啟動讀取-修改-寫入序列。(c) 如果用戶端在系統狀態明確修正前不應重試,請使用 FAILED_PRECONDITION。舉例來說,如果「rmdir」因目錄不為空而失敗,則應傳回 FAILED_PRECONDITION,因為除非從目錄中刪除檔案,否則用戶端不應重試。

HTTP 對應:400 錯誤的要求

ABORTED

作業已取消,通常是因為例如順序器檢查失敗或交易已取消等並行問題所導致。

如要決定採用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE,請參閱以上指南。

HTTP 對應:409 衝突

OUT_OF_RANGE

嘗試作業時超過有效範圍,例如搜尋或讀取超過檔案結尾。

與 INVALID_ARGUMENT 不同,此錯誤表示如果系統狀態變更則可修正的問題。舉例來說,如果要求 32 位元檔案系統在 [0,2^32-1] 範圍以外的偏移量讀取,系統會產生 INVALID_ARGUMENT,但如果要求從超過目前檔案大小的偏移量讀取,系統會產生 OUT_OF_RANGE。

FAILED_PRECONDITION 與 OUT_OF_RANGE 之間有不少重疊的地方。我們建議您在適用時使用 OUT_OF_RANGE (較為特定的錯誤),這樣在空間中進行迭代作業的呼叫者就可以在完成時輕鬆找到要偵測的 OUT_OF_RANGE 錯誤。

HTTP 對應:400 錯誤的要求

UNIMPLEMENTED

未實作作業或作業在此服務中不受支援/未啟用。

HTTP 對應:501 未實作

INTERNAL

內部錯誤。這表示基礎系統預期的某些不變的情形已被打破。此錯誤代碼保留供嚴重錯誤使用。

HTTP 對應:500 內部伺服器錯誤

UNAVAILABLE

服務目前無法使用,這極有可能是暫時情況,並能透過重試來修正。請注意,重試非冪等作業不一定安全。

如要決定採用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE,請參閱以上指南。

HTTP 對應:503 服務不可用

DATA_LOSS

無法復原的資料遺失或損毀。

HTTP 對應:500 內部伺服器錯誤