資源與收藏
建議變更
PDF
Astra Control REST API可讓您存取資源執行個體和資源執行個體集合。
|
從概念上來說、REST 資源*類似於以物件導向程式設計（OOP）語言和系統所定義的*物件。有時這些術語會互換使用。但一般而言、在外部REST API的內容中使用「資源」是偏好的、而「物件」則是用於儲存在伺服器上的對應狀態執行個體資料。 |
Astra資源的屬性
Astra Control REST API符合RESTful設計原則。每個Astra資源執行個體都是根據明確定義的資源類型來建立。一組相同類型的資源執行個體稱為*集合*。API呼叫會對個別資源或資源集合起作用。
Astra Control REST API隨附的資源類型具有下列特性：
-
每種資源類型都是使用架構來定義（通常是在Json中）
-
每個資源架構都包含資源類型和版本
-
資源類型是全域唯一的
透過Astra Control REST API提供的資源執行個體具有下列特性：
-
資源執行個體是根據單一資源類型建立
-
資源類型會使用「媒體類型」值來表示
-
執行個體由Astra服務維護的狀態資料組成
-
每個執行個體都可透過專屬且長效的URL存取
-
如果資源執行個體可以有多種表示形式、則可以使用不同的媒體類型來要求所需的表示形式
透過Astra Control REST API提供的資源集合具有下列特性：
-
單一資源類型的資源執行個體集稱為集合
-
資源集合具有獨特且長久存在的URL
每個資源執行個體都會在建立時指派一個識別碼。此識別碼為128位元UUIDv4值。指派的UUUIDv4值是全域唯一且不可變的。發出API呼叫以建立新執行個體之後、會在HTTP回應的「位置」標頭中、將具有相關ID的URL傳回給呼叫者。您可以擷取識別碼、並在參照資源執行個體時用於後續通話。
|
|
資源識別碼是用於集合的主要金鑰。 |
Astra資源的通用架構
每個Astra Control資源都是使用通用結構來定義。
每個Astra資源都包含下表所示的關鍵值。
| 金鑰 | 說明 |
|---|---|
類型 |
一種全域唯一的資源類型、稱為*資源類型*。 |
版本 |
稱為*資源版本*的版本識別碼。 |
ID |
全域唯一識別碼、稱為*資源識別碼*。 |
中繼資料 |
包含各種資訊的Json物件、包括使用者和系統標籤。 |
每個Astra資源隨附的中繼資料Json物件包含下表所示的索引鍵值。
| 金鑰 | 說明 |
|---|---|
標籤 |
與資源相關聯之用戶端指定標籤的Json陣列。 |
建立時間戳記 |
Json字串包含時間戳記、指出資源建立的時間。 |
修改時間戳記 |
Json字串包含ISO-8601格式化時間戳記、指出上次變更資源的時間。 |
建立者 |
Json字串、包含建立資源之使用者ID的UUIDv4識別碼。如果資源是由內部系統元件所建立、且與建立實體沒有相關聯的UUID、則會使用* null * UUID。 |
所選資源是一種「最大」值、用於協調生命週期轉換和控制存取。