Time Series Instances - Execute Batch

服務:: Time Series Insights

API 版本:: 2020-07-31

對多個時序實例執行批量獲取、創建、更新、刪除作。

POST https://{environmentFqdn}/timeseries/instances/$batch?api-version=2020-07-31

URI 參數

名稱	位於	必要	類型	Description
environmentFqdn	path	True	string	每個環境 FQDN，例如 10000000-0000-0000-0000-100000000109.env.timeseries.azure.com。您可以從取得環境 API、Azure 入口網站或 Azure Resource Manager 的回應取得此功能變數名稱。
api-version	query	True	string	要與用戶端要求搭配使用的 API 版本。目前支援的版本是「2020-07-31」。

要求標頭

名稱	必要	類型	Description
x-ms-client-request-id		string	選擇性用戶端要求識別碼。服務會記錄此值。允許服務追蹤服務之間的作業，並允許客戶連絡有關特定要求的支持人員。
x-ms-client-session-id		string	選擇性用戶端會話識別碼。服務會記錄此值。允許服務追蹤跨服務的相關作業群組，並允許客戶連絡有關特定要求群組的支持人員。

要求本文

名稱	類型	Description
delete	InstancesRequestBatchGetOrDelete	要刪除的時序實例。可以指定時序 ID 或名稱。
get	InstancesRequestBatchGetOrDelete	要返回的時序 ID 或時序實例的名稱。
put	TimeSeriesInstance[]	要創建或更新的時間序列實例。
update	TimeSeriesInstance[]	要更新的時間序列實例。如果實例不存在，則返回錯誤。

回應

名稱	類型	Description
200 OK	InstancesBatchResponse	作業成功。標題 x-ms-request-id: string
Other Status Codes	TsiError	非預期的錯誤。標題 x-ms-request-id: string

名稱

類型

Description

200 OK

InstancesBatchResponse

作業成功。

標題

x-ms-request-id: string

Other Status Codes

TsiError

非預期的錯誤。

標題

x-ms-request-id: string

安全性

azure_auth

Azure Active Directory OAuth2 流

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
user_impersonation	模擬您的用戶帳戶

範例

InstancesBatchDeleteByIds

InstancesBatchDeleteByNames

InstancesBatchGetByIds

InstancesBatchGetByNames

InstancesBatchPut

InstancesBatchUpdate

InstancesBatchDeleteByIds

範例要求

HTTP

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31

{
  "delete": {
    "timeSeriesIds": [
      [
        "2da181d7-8346-4cf2-bd94-a17742237429",
        "T1"
      ],
      [
        "18672e3d-2beb-4007-9846-042b09ef3c72",
        "T2"
      ]
    ]
  }
}

範例回覆

狀態碼:: 200

{
  "delete": [
    null,
    {
      "code": "InvalidInput",
      "message": "Time series instance with ID '[\"18672e3d-2beb-4007-9846-042b09ef3c72\", \"T2\"]' cannot be deleted. There are already ingested events associated with this time series ID.",
      "innerError": {
        "code": "CannotDeleteInstance"
      }
    }
  ]
}

InstancesBatchDeleteByNames

範例要求

HTTP

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31

{
  "delete": {
    "names": [
      "F2W6.GF",
      "F1W7.GS1"
    ]
  }
}

範例回覆

狀態碼:: 200

{
  "delete": [
    null,
    {
      "code": "InvalidInput",
      "message": "Time series instance with ID '[\"18672e3d-2beb-4007-9846-042b09ef3c72\", \"T2\"]' cannot be deleted. There are already ingested events associated with this time series ID.",
      "innerError": {
        "code": "CannotDeleteInstance"
      }
    }
  ]
}

InstancesBatchGetByIds

範例要求

HTTP

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31

{
  "get": {
    "timeSeriesIds": [
      [
        "006dfc2d-0324-4937-998c-d16f3b4f1952",
        "T1"
      ]
    ]
  }
}

範例回覆

狀態碼:: 200

{
  "get": [
    {
      "instance": {
        "typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
        "name": "F1W7.GS1",
        "timeSeriesId": [
          "006dfc2d-0324-4937-998c-d16f3b4f1952",
          "T1"
        ],
        "description": "ContosoFarm1W7_GenSpeed1",
        "hierarchyIds": [
          "33d72529-dd73-4c31-93d8-ae4e6cb5605d"
        ],
        "instanceFields": {
          "Name": "GeneratorSpeed",
          "Plant": "Contoso Plant 1",
          "Unit": "W7",
          "System": "Generator System",
          "Status": false,
          "Version": 1.3,
          "Code": 28
        }
      }
    }
  ]
}

InstancesBatchGetByNames

範例要求

HTTP

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31

{
  "get": {
    "names": [
      "F1W7.GS1"
    ]
  }
}

範例回覆

狀態碼:: 200

{
  "get": [
    {
      "instance": {
        "typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
        "name": "F1W7.GS1",
        "timeSeriesId": [
          "006dfc2d-0324-4937-998c-d16f3b4f1952",
          "T1"
        ],
        "description": "ContosoFarm1W7_GenSpeed1",
        "hierarchyIds": [
          "33d72529-dd73-4c31-93d8-ae4e6cb5605d"
        ],
        "instanceFields": {
          "Name": "GeneratorSpeed",
          "Plant": "Contoso Plant 1",
          "Unit": "W7",
          "System": "Generator System",
          "Status": false,
          "Version": 1.3,
          "Code": 28
        }
      }
    }
  ]
}

InstancesBatchPut

範例要求

HTTP

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31

{
  "put": [
    {
      "typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
      "name": "F1W7.GS1",
      "timeSeriesId": [
        "006dfc2d-0324-4937-998c-d16f3b4f1952",
        "T1"
      ],
      "description": "ContosoFarm1W7_GenSpeed1",
      "hierarchyIds": [
        "33d72529-dd73-4c31-93d8-ae4e6cb5605d"
      ],
      "instanceFields": {
        "Name": "GeneratorSpeed",
        "Plant": "Contoso Plant 1",
        "Unit": "W7",
        "System": "Generator System",
        "Status": false,
        "Version": 1.3,
        "Code": 28
      }
    }
  ]
}

範例回覆

狀態碼:: 200

{
  "put": [
    {
      "error": null
    }
  ]
}

InstancesBatchUpdate

範例要求

HTTP

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31

{
  "update": [
    {
      "typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
      "name": "F1W7.GS1",
      "timeSeriesId": [
        "006dfc2d-0324-4937-998c-d16f3b4f1952",
        "T1"
      ],
      "description": "ContosoFarm1W7_GenSpeed1",
      "hierarchyIds": [
        "33d72529-dd73-4c31-93d8-ae4e6cb5605d"
      ],
      "instanceFields": {
        "Name": "GeneratorSpeed",
        "Plant": "Contoso Plant 1",
        "Unit": "W7",
        "System": "Generator System",
        "Status": false,
        "Version": 1.3,
        "Code": 28
      }
    }
  ]
}

範例回覆

狀態碼:: 200

{
  "update": [
    {
      "error": null
    }
  ]
}

定義

名稱	Description
InstanceOrError	對特定時序實例進行批處理作的結果。作成功時設置實例物件（放置作除外），作不成功時設置錯誤物件。
InstancesBatchRequest	請求對一批實例執行單個作。必須設置“get”、“put”、“update”或“delete”中的一個。
InstancesBatchResponse	對一批實例的單個作的回應。根據請求，只設置“get”、“put”、“update”或“delete”中的一個。
InstancesRequestBatchGetOrDelete	請求按時序 ID 或時序名稱獲取或刪除實例。必須設置“timeSeriesIds”或“names”中的一個。
TimeSeriesInstance	時序實例是時序本身。在大多數情況下，deviceId 或 assetId 是環境中資產的唯一標識符。實例具有與之關聯的描述性資訊，稱為實例欄位。實例欄位至少包含層次結構資訊。它們還可以包括有用的描述性數據，例如製造商、運營商或最後服務日期。
TsiError	API 錯誤的相關信息。
TsiErrorBody	具有錯誤碼和訊息的特定 API 錯誤。
TsiErrorDetails	其他錯誤資訊。

InstanceOrError

Object

對特定時序實例進行批處理作的結果。作成功時設置實例物件（放置作除外），作不成功時設置錯誤物件。

名稱	類型	Description
error	TsiErrorBody	錯誤物件 - 當作業失敗時設定。
instance	TimeSeriesInstance	時間序列實例物件 - 在作成功時設置（放置作除外）。

InstancesBatchRequest

Object

請求對一批實例執行單個作。必須設置“get”、“put”、“update”或“delete”中的一個。

名稱	類型	Description
delete	InstancesRequestBatchGetOrDelete	要刪除的時序實例。可以指定時序 ID 或名稱。
get	InstancesRequestBatchGetOrDelete	要返回的時序 ID 或時序實例的名稱。
put	TimeSeriesInstance[]	要創建或更新的時間序列實例。
update	TimeSeriesInstance[]	要更新的時間序列實例。如果實例不存在，則返回錯誤。

InstancesBatchResponse

Object

對一批實例的單個作的回應。根據請求，只設置“get”、“put”、“update”或“delete”中的一個。

名稱	類型	Description
delete	TsiErrorBody[]	按位置對應於請求中「delete」陣列的錯誤物件清單。 Null 表示實例已被刪除或不存在。當作不成功時（例如，當存在與此時間序列實例關聯的事件時），將設置 Error 物件。
get	InstanceOrError[]	按位置對應於請求中「get」陣列的實例或錯誤對象的清單。作成功時設置實例物件，作不成功時設置錯誤物件。
put	InstanceOrError[]	按位置對應於請求中「put」陣列的錯誤物件清單。作不成功時設置錯誤物件。
update	InstanceOrError[]	按位置對應於請求中「update」陣列的錯誤物件清單。作成功時設置實例物件，作不成功時設置錯誤物件。

InstancesRequestBatchGetOrDelete

Object

請求按時序 ID 或時序名稱獲取或刪除實例。必須設置“timeSeriesIds”或“names”中的一個。

名稱	類型	Description
names	string[]	要返回或刪除的時間序列實例的名稱清單。
timeSeriesIds	TimeSeriesId[]	要返回或刪除的時序實例的時序ID清單。

TimeSeriesInstance

Object

時序實例是時序本身。在大多數情況下，deviceId 或 assetId 是環境中資產的唯一標識符。實例具有與之關聯的描述性資訊，稱為實例欄位。實例欄位至少包含層次結構資訊。它們還可以包括有用的描述性數據，例如製造商、運營商或最後服務日期。

名稱	類型	Description
description	string	此可選欄位包含有關實例的說明。
hierarchyIds	string[]	實例所屬的時序層次結構ID集。可能是 Null。
instanceFields		包含使用者定義的實例屬性的鍵值對集。它可能是空。支援的屬性值類型為：bool、string、long、double，並且不能嵌套或 null。
name	string	在環境中唯一的實例的可選名稱。名稱充當時序實例的可變別名或顯示名稱。可變，可能為 null。
timeSeriesId	TimeSeriesId[]	唯一標識實例的時序ID。它與環境中的時序ID屬性匹配。不可變，從不為空。
typeId	string	這表示此實例所屬的類型。永不為 Null。

TsiError

Object

API 錯誤的相關信息。

名稱	類型	Description
error	TsiErrorBody	具有錯誤碼和訊息的特定 API 錯誤。

TsiErrorBody

Object

具有錯誤碼和訊息的特定 API 錯誤。

名稱	類型	Description
code	string	語言無關、人類可讀取的字串，可定義服務特定的錯誤碼。此程式代碼可作為回應中指定的 HTTP 錯誤碼更明確的指標。可用來以程式設計方式處理特定錯誤案例。
details	TsiErrorDetails[]	包含其他錯誤資訊。可能是 Null。
innerError	TsiErrorBody	包含更具體的錯誤，可縮小原因。可能是 Null。
message	string	人類可讀且與語言無關的錯誤表示法。其用途是開發人員的協助，不適合接觸終端使用者。
target	string	特定錯誤的目標（例如，錯誤中的屬性名稱）。可能是 Null。

TsiErrorDetails

Object

其他錯誤資訊。

名稱	類型	Description
code	string	語言無關、人類可讀取的字串，可定義服務特定的錯誤碼。此程式代碼可作為回應中指定的 HTTP 錯誤碼更明確的指標。可用來以程式設計方式處理特定錯誤案例。
message	string	人類可讀且與語言無關的錯誤表示法。其用途是開發人員的協助，不適合接觸終端使用者。

共用方式為

Time Series Instances - Execute Batch

URI 參數

要求標頭

要求本文

回應

安全性

azure_auth

範圍

範例

InstancesBatchDeleteByIds

範例要求

範例回覆

InstancesBatchDeleteByNames

範例要求

範例回覆

InstancesBatchGetByIds

範例要求

範例回覆

InstancesBatchGetByNames

範例要求

範例回覆

InstancesBatchPut

範例要求

範例回覆

InstancesBatchUpdate

範例要求

範例回覆

定義

InstanceOrError

InstancesBatchRequest

InstancesBatchResponse

InstancesRequestBatchGetOrDelete

TimeSeriesInstance

TsiError

TsiErrorBody

TsiErrorDetails