本繁體中文版使用機器翻譯,譯文僅供參考,若與英文版本牴觸,應以英文版本為準。

HTTP詳細資料

Astra Control REST API使用HTTP及相關參數來處理資源和集合。HTTP實作的詳細資料如下。

API交易與CRUD模式

Astra Control REST API實作交易模式、提供定義完善的作業和狀態轉換。

每個REST API呼叫都會以HTTP要求的形式執行、以供Astra服務使用。每個要求都會產生與用戶端相關的回應。此要求回應配對可視為API交易。

每個透過Astra Control REST API提供的資源執行個體和集合、都是根據* CRUD*模型來存取。共有四項作業、每項作業對應至單一HTTP方法。這些作業包括:

  • 建立

  • 讀取

  • 更新

  • 刪除

對於部分Astra資源、僅支援其中一部分作業。您應該檢閱 "API 參考" 以取得特定API呼叫的詳細資訊。

HTTP方法

下表顯示API支援的HTTP方法或動詞。

方法 CRUD 說明

取得

讀取

擷取資源執行個體或集合的物件屬性。當與集合一起使用時、這被視為* list*作業。

貼文

建立

根據輸入參數建立新的資源執行個體。長期URL會以「位置」回應標頭傳回。

放入

更新

使用隨附的Json要求本文來更新整個資源執行個體。無法使用者修改的關鍵值會保留下來。

刪除

刪除

刪除現有的資源執行個體。

要求和回應標頭

下表摘要說明Astra Control REST API所使用的HTTP標頭。

附註 請參閱 "RFC 7232.""RFC 7233" 以取得更多資訊。
標頭 類型 使用注意事項

接受

申請

如果值為「/」或未提供、則會在內容類型回應標頭中傳回「application/json」。如果該值設為Astra資源媒體類型、則內容類型標頭會傳回相同的媒體類型。

授權

申請

含有使用者API金鑰的承載權杖。

內容類型

回應

根據「Accept(接受)」要求標頭傳回。

ETag

回應

隨附於RFC 7232.定義的成功。此值是整個Json資源之MD5值的十六進位表示法。

如果相符

申請

如3.1 RFC 72332節所述實作的先決條件要求標頭、並支援* PUT *要求。

IF修改日期

申請

如第3.4節RFC 72332所述實作的先決條件要求標頭、並支援* PUT *要求。

如果沒有修改、自此

申請

如第3.4節RFC 72332所述實作的先決條件要求標頭、並支援* PUT *要求。

位置

回應

包含新建立資源的完整URL。

查詢參數

下列查詢參數可用於資源集合。請參閱 "使用集合" 以取得更多資訊。

查詢參數 說明

包括

包含讀取集合時應傳回的欄位。

篩選器

表示讀取集合時、資源必須符合的欄位。

訂單者

決定讀取集合時傳回資源的排序順序。

限制

限制讀取集合時傳回的資源上限。

跳過

設定讀取集合時要經過和跳過的資源數目。

指出中繼資料物件是否應傳回資源總數。

HTTP 狀態代碼

Astra Control REST API使用的HTTP狀態代碼如下所述。

附註 Astra Control REST API也使用*問題詳細資料做為HTTP API*標準。請參閱 "診斷與支援" 以取得更多資訊。
程式碼 意義 說明

200

好的

表示未建立新資源執行個體的通話成功。

201.

已建立

已成功建立物件、且位置回應標頭包含該物件的唯一識別碼。

204.

無內容

雖然未傳回任何內容、但要求仍成功。

400

錯誤要求

無法辨識或不適當的要求輸入。

401.

未獲授權

使用者未獲授權、必須經過驗證。

403.

禁止

由於授權錯誤、存取遭拒。

404..

找不到

要求中提及的資源不存在。

409.

衝突

建立物件的嘗試失敗、因為物件已經存在。

500

內部錯誤

伺服器發生一般內部錯誤。

503

服務無法使用

由於某些原因、服務尚未準備好處理要求。