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

資源與收藏

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。

所選資源是一種「最大」值、用於協調生命週期轉換和控制存取。