Time Series Instances - Execute Batch

參考

Service:: Time Series Insights

API Version:: 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	要刪除的時間序列實例。可以指定時間序列識別碼或名稱。
get	InstancesRequestBatchGetOrDelete	要傳回之時間序列實例的時間序列標識碼或名稱。
put	TimeSeriesInstance[]	要建立或更新的時間序列實例。
update	TimeSeriesInstance[]	要更新的時間序列實例。如果實例不存在，則會傳回錯誤。

回應

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

名稱

類型

Description

200 OK

InstancesBatchResponse

成功的作業。

Headers

x-ms-request-id: string

Other Status Codes

TsiError

非預期的錯誤。

Headers

x-ms-request-id: string

安全性

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

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

範例

InstancesBatchDeleteByIds

InstancesBatchDeleteByNames

InstancesBatchGetByIds

InstancesBatchGetByNames

InstancesBatchPut

InstancesBatchUpdate

InstancesBatchDeleteByIds

Sample Request

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"
      ]
    ]
  }
}

Sample Response

Status code:: 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

Sample Request

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"
    ]
  }
}

Sample Response

Status code:: 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

Sample Request

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"
      ]
    ]
  }
}

Sample Response

Status code:: 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

Sample Request

HTTP

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

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

Sample Response

Status code:: 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

Sample Request

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
      }
    }
  ]
}

Sample Response

Status code:: 200

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

InstancesBatchUpdate

Sample Request

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
      }
    }
  ]
}

Sample Response

Status code:: 200

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

定義

名稱	Description
InstanceOrError	特定時間序列實例上的批次作業結果。作業成功時會設定實例物件 (，但作業失敗時會設定 put 作業) 和錯誤物件。
InstancesBatchRequest	要求在實例批次上執行單一作業。必須設定「get」、「put」、「更新」或「刪除」的其中一個。
InstancesBatchResponse	一批實例上單一作業的回應。只會根據要求設定「get」、“put”、“update” 或 “delete” 的其中一個。
InstancesRequestBatchGetOrDelete	依時間序列標識碼或時間序列名稱取得或刪除實例的要求。必須設定「timeSeriesIds」或「名稱」的其中一個。
TimeSeriesInstance	時間序列實例是時間序列本身。在大部分情況下，它們是 deviceId 或 assetId，也就是資產在環境中的唯一識別碼。實例具有與其相關聯的描述性資訊，稱為實例欄位。實例欄位至少包含階層資訊。它們也可以包含有用的描述性資料，像是製造商、操作員或上次維護日期。
TsiError	API 錯誤的相關信息。
TsiErrorBody	具有錯誤碼和訊息的特定 API 錯誤。
TsiErrorDetails	其他錯誤資訊。

InstanceOrError

特定時間序列實例上的批次作業結果。作業成功時會設定實例物件 (，但作業失敗時會設定 put 作業) 和錯誤物件。

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

InstancesBatchRequest

要求在實例批次上執行單一作業。必須設定「get」、「put」、「更新」或「刪除」的其中一個。

名稱	類型	Description
delete	InstancesRequestBatchGetOrDelete	要刪除的時間序列實例。可以指定時間序列識別碼或名稱。
get	InstancesRequestBatchGetOrDelete	要傳回之時間序列實例的時間序列標識碼或名稱。
put	TimeSeriesInstance[]	要建立或更新的時間序列實例。
update	TimeSeriesInstance[]	要更新的時間序列實例。如果實例不存在，則會傳回錯誤。

InstancesBatchResponse

一批實例上單一作業的回應。只會根據要求設定「get」、“put”、“update” 或 “delete” 的其中一個。

名稱	類型	Description
delete	TsiErrorBody[]	依位置對應至要求中「delete」陣列的錯誤物件清單。 Null 表示實例已刪除或不存在。當作業失敗 (時，就會設定錯誤物件，例如當有與此時間序列實例相關聯的事件時) 。
get	InstanceOrError[]	要求中位置對應至「get」陣列的實體或錯誤物件清單。當作業成功時，就會設定實例物件，並在作業失敗時設定錯誤物件。
put	InstanceOrError[]	依位置對應至要求中「put」陣列的錯誤物件清單。當作業失敗時，就會設定 Error 物件。
update	InstanceOrError[]	依位置對應至要求中「update」陣列的錯誤物件清單。當作業成功時，就會設定實例物件，並在作業失敗時設定錯誤物件。

InstancesRequestBatchGetOrDelete

依時間序列標識碼或時間序列名稱取得或刪除實例的要求。必須設定「timeSeriesIds」或「名稱」的其中一個。

名稱	類型	Description
names	string[]	要傳回或刪除之時間序列實例的名稱清單。
timeSeriesIds	TimeSeriesId[]	要傳回或刪除之時間序列實例的時間序列標識符清單。

TimeSeriesInstance

時間序列實例是時間序列本身。在大部分情況下，它們是 deviceId 或 assetId，也就是資產在環境中的唯一識別碼。實例具有與其相關聯的描述性資訊，稱為實例欄位。實例欄位至少包含階層資訊。它們也可以包含有用的描述性資料，像是製造商、操作員或上次維護日期。

名稱	類型	Description
description	string	這個選擇性欄位包含實例的相關描述。
hierarchyIds	string[]	實例所屬的時間序列階層標識碼集。可能是 Null。
instanceFields		包含使用者定義實例屬性的索引鍵/值組集。可能為 Null。支援的屬性值類型為：bool、string、long、double，而且不能巢狀或 null。
name	string	環境中唯一的實例選擇性名稱。名稱可作為可變別名或時間序列實例的顯示名稱。可變動，可能是 Null。
timeSeriesId	TimeSeriesId[]	可唯一識別實例的時間序列標識碼。它會比對環境中的時間序列標識碼屬性。不可變，永不為 Null。
typeId	string	這代表這個實例所屬的類型。絕對不會是 null。

TsiError

API 錯誤的相關信息。

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

TsiErrorBody

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

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

TsiErrorDetails

其他錯誤資訊。

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

共用方式為

Time Series Instances - Execute Batch

URI 參數

要求標頭

要求本文

回應

安全性

azure_auth

Scopes

範例

InstancesBatchDeleteByIds

Sample Request

Sample Response

InstancesBatchDeleteByNames

Sample Request

Sample Response

InstancesBatchGetByIds

Sample Request

Sample Response

InstancesBatchGetByNames

Sample Request

Sample Response

InstancesBatchPut

Sample Request

Sample Response

InstancesBatchUpdate

Sample Request

Sample Response

定義

InstanceOrError

InstancesBatchRequest

InstancesBatchResponse

InstancesRequestBatchGetOrDelete

TimeSeriesInstance

TsiError

TsiErrorBody

TsiErrorDetails

其他資源