HTTP詳細資料
建議變更
PDF
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" 以取得更多資訊。 |
| 標頭 | 類型 | 使用注意事項 |
|---|---|---|
接受 |
申請 |
如果值為「/」或未提供、 |
授權 |
申請 |
含有使用者API金鑰的承載權杖。 |
內容類型 |
回應 |
根據傳回 |
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 |
服務無法使用 |
由於某些原因、服務尚未準備好處理要求。 |