Twins - DigitalTwins Add

Service:

Azure Digital Twins

API Version:

2023-10-31

加入或取代數位對應項。 狀態碼：

• 200 確定
• 400 不正確的要求
  • InvalidArgument - 數位對應項識別碼或承載無效。
  • ModelDecommissioned - 數位對應項的模型已解除委任。
  • TwinLimitReached - 已達到允許的數位對應項數目上限。
  • ValidationFailed - 數位對應項承載無效。
• 412 先決條件失敗
  • PreconditionFailed - 先決條件檢查 (If-Match 或 If-None-Match) 失敗。

PUT https://digitaltwins-hostname/digitaltwins/{id}?api-version=2023-10-31

URI 參數

名稱	位於	必要	類型	Description
id	path	True	string	數位對應項的識別碼。 識別碼在服務內是唯一的，且區分大小寫。
api-version	query	True	string	要求的 API 版本。

要求標頭

名稱	必要	類型	Description
If-None-Match		string	只有在實體不存在時，才執行作業。
traceparent		string	識別分散式追蹤系統中的要求。
tracestate		string	提供廠商特定的追蹤識別資訊，而且是追蹤親和的隨附專案。

要求本文

名稱	類型	Description
twin	object	要加入的數位對應項實例。 如果提供，則會忽略$dtId屬性。

回應

名稱	類型	Description
200 OK	DigitalTwin	Success Headers ETag: string
Other Status Codes	ErrorResponse	預設回應。 Headers x-ms-error-code: string

安全性

oauth2

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize?resource=0b07f429-9f4b-4714-9392-cc5e8e80c8b0

範例

Add a digital twin

Add a digital twin (with properties and components)

Add a digital twin

Sample Request

HTTP

PUT https://digitaltwins-hostname/digitaltwins/myNewTwinId?api-version=2023-10-31

{
  "$metadata": {
    "$model": "dtmi:com:example:interfaces:interfaceName;1"
  }
}

Sample Response

Status code:

200

{
  "$dtId": "myNewTwinId",
  "$metadata": {
    "$model": "dtmi:com:example:interfaces:interfaceName;1",
    "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
  }
}

Add a digital twin (with properties and components)

Sample Request

HTTP

PUT https://digitaltwins-hostname/digitaltwins/myNewTwinId?api-version=2023-10-31


{
  "$metadata": {
    "$model": "dtmi:com:example:interfaces:interfaceName;1",
    "property1": {
      "sourceTime": "2022-05-31T12:00:01.000125009Z"
    }
  },
  "property1": 1,
  "property2": {
    "subProperty1": "some value",
    "subProperty2": "some other value"
  },
  "component1": {
    "$metadata": {
      "componentProperty": {
        "sourceTime": "2022-05-31T12:00:00.000125009Z"
      }
    },
    "componentProperty": "some value"
  }
}

Sample Response

Status code:

200

{
  "$dtId": "myNewTwinId",
  "$etag": "W/\"9c2876c2-aff0-40b3-9fba-0c6be9d020a6\"",
  "property1": 1,
  "property2": {
    "subProperty1": "some value",
    "subProperty2": "some other value"
  },
  "component1": {
    "componentProperty": "some value",
    "$metadata": {
      "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
      "componentProperty": {
        "lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
        "sourceTime": "2022-05-31T12:00:01.000125009Z"
      }
    }
  },
  "$metadata": {
    "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
    "$model": "dtmi:com:example:interfaces:interfaceName;1",
    "property1": {
      "lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
      "sourceTime": "2022-05-31T12:00:01.000125009Z"
    },
    "property2": {
      "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
    }
  }
}

定義

名稱	Description
Error	錯誤定義。
ErrorResponse	錯誤回應。
InnerError	比包含的錯誤所提供的更具體錯誤描述。

Error

錯誤定義。

名稱	類型	Description
code	string	服務特定的錯誤碼，可作為 HTTP 錯誤碼的子狀態。
details	Error[]	內部錯誤詳細資料。
innererror	InnerError	物件，包含比目前物件有關錯誤的更特定資訊。
message	string	人類看得懂的錯誤標記法。

ErrorResponse

錯誤回應。

名稱	類型	Description
error	Error	錯誤詳細資料。

InnerError

比包含的錯誤所提供的更具體錯誤描述。

名稱	類型	Description
code	string	比包含的錯誤所提供的更具體錯誤碼。
innererror	InnerError	物件，包含比目前物件有關錯誤的更特定資訊。