IoT Central REST API を使用してジョブの作成と管理を行う方法

[アーティクル]
10/22/2024

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。 REST API を使用して、IoT Central アプリケーションでジョブの作成と管理を行えます。 REST API を使用すると、次を行うことができます。

アプリケーションでジョブを一覧表示し、ジョブの詳細を表示します。
アプリケーションでジョブを作成して実行します。
アプリケーションでジョブを停止、再開、再実行します。
アプリケーションでジョブをスケジュールし、スケジュールされたジョブの詳細を表示します。

スケジュールされたジョブは、将来実行されるように作成されます。スケジュールされたジョブが 1 回限り、毎日、または毎週実行されるように、開始日時を設定できます。スケジュールされていないジョブは 1 回だけ実行されます。

この記事では、/jobs/{job_id} API を使用してデバイスを一括で制御する方法について説明します。デバイスは個別に制御することもできます。

すべての IoT Central REST API 呼び出しに承認ヘッダーが必要です。詳細については、「IoT Central REST API 呼び出しを認証および承認する方法」を参照してください。

IoT Central REST API のリファレンスドキュメントについては、「Azure IoT Central REST API リファレンス」をご覧ください。

UI でジョブを作成および管理する方法については、「Azure IoT Central アプリケーションでデバイスを一括管理する」を参照してください。

ジョブペイロード

この記事で説明する API の多くには、次の JSON スニペットのような定義が含まれています。

{
  "id": "job-014",
  "displayName": "Set target temperature",
  "description": "Set target temperature for all thermostat devices",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "56"
    }
  ],
  "status": "complete"
}

次の表では、前の JSON スニペット内のフィールドについて説明します。

フィールド	説明
`id`	アプリケーション内のジョブの一意の ID。
`displayName`	アプリケーション内のジョブの表示名。
`description`	ジョブの説明。
`group`	ジョブが適用されるデバイスグループの ID。アプリケーション内のデバイスグループの一覧を取得するには、`deviceGroups` プレビュー REST API を使用します。
`status`	ジョブの状態。 `complete`、`cancelled`、`failed`、`pending`、`running`、`stopped` のいずれかです。
`batch`	このセクションが存在する場合、ジョブ内のデバイスをバッチ処理する方法を定義します。
`batch/type`	各バッチのサイズは、グループ内のデバイス合計の `percentage` か、デバイスの `number` です。
`batch/value`	各バッチ内のデバイスの割合またはデバイスの数のいずれか。
`cancellationThreshold`	このセクションが存在する場合、ジョブのキャンセルしきい値を定義します。
`cancellationThreshold/batch`	`true` または `false`。 True の場合、キャンセルしきい値はバッチごとに設定されます。 `false` の場合、キャンセルしきい値はジョブ全体に適用されます。
`cancellationThreshold/type`	ジョブのキャンセルしきい値は、デバイスの `percentage` または `number` のいずれかです。
`cancellationThreshold/value`	キャンセルしきい値を定義するデバイスの割合またはデバイスの数のいずれか。
`data`	ジョブによって実行される操作の配列。
`data/type`	`PropertyJobData`、`CommandJobData`、`CloudPropertyJobData`、または `DeviceTemplateMigrationJobData` のいずれかです。 API のプレビューバージョンには `DeviceManifestMigrationJobData` が含まれています。
`data/target`	ターゲットデバイスのモデル ID。
`data/path`	プロパティ、コマンド、またはクラウドプロパティの名前。
`data/value`	設定するプロパティ値、または送信するコマンドパラメーター。

ジョブ情報の取得

アプリケーション内のジョブの一覧を取得するには、次の要求を使用します。

GET https://{your app subdomain}.azureiotcentral.com/api/jobs?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
  "value": [
    {
      "id": "job-006",
      "displayName": "Set customer name",
      "description": "Set the customer name cloud property",
      "group": "4fcbec3b-5ee8-4324-855d-0f03b56bcf7f",
      "data": [
        {
          "type": "CloudPropertyJobData",
          "target": "dtmi:modelDefinition:bojo9tfju:yfvu5gv2vl",
          "path": "CustomerName",
          "value": "Contoso"
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-005",
      "displayName": "Set target temperature",
      "description": "Set target temperature device property",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "data": [
        {
          "type": "PropertyJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "targetTemperature",
          "value": 56
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-004",
      "displayName": "Run device report",
      "description": "Call command to run the device reports",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "batch": {
        "type": "percentage",
        "value": 25
      },
      "cancellationThreshold": {
        "type": "percentage",
        "value": 10,
        "batch": false
      },
      "data": [
        {
          "type": "CommandJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "getMaxMinReport",
          "value": "2021-06-15T05:00:00.000Z"
        }
      ],
      "status": "complete"
    }
  ]
}

次の要求を使用して、ID で個々のジョブを取得します。

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
  "id": "job-004",
  "displayName": "Run device report",
  "description": "Call command to run the device reports",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "CommandJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "getMaxMinReport",
      "value": "2021-06-15T05:00:00.000Z"
    }
  ],
  "status": "complete"
}

次の要求を使用して、ジョブ内のデバイスの詳細を取得します。

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004/devices?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
  "value": [
    {
      "id": "therm-01",
      "status": "completed"
    },
    {
      "id": "therm-02",
      "status": "completed"
    },
    {
      "id": "therm-03",
      "status": "completed"
    },
    {
      "id": "therm-04",
      "status": "completed"
    }
  ]
}

ジョブの作成

ジョブを作成するには、次の要求を使用します。

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006?api-version=2022-07-31

要求本文の group フィールドによって、IoT Central アプリケーション内でデバイスグループが識別されます。ジョブでは、ジョブが動作するデバイスのセットを識別するために、デバイスグループを使用します。

適切なデバイスグループがまだない場合は、REST API 呼び出しで作成できます。次の例では、group1 をグループ ID として、デバイスグループを作成しています。

PUT https://{your app subdomain}/api/deviceGroups/group1?api-version=2022-07-31

デバイスグループを作成するときに、グループが含まれるようにデバイスが選択される filter を定義します。フィルターによって、デバイステンプレート、および一致するプロパティが識別されます。次の例では、provisioned プロパティが true である "dtmi:modelDefinition:dtdlv2" デバイステンプレートに関連付けられているすべてのデバイスを含むデバイスグループを作成します

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

この要求に対する応答は、次の例のようになります。

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

これで、応答からの id 値を使用して、新しいジョブを作成できるようになりました。

{
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ]
}

この要求に対する応答は、次の例のようになります。最初のジョブの状況は、次に対する pending です:

{
  "id": "job-006",
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ],
  "status": "pending"
}

ジョブの停止、再開、および再実行

次の要求を使用して、実行中のジョブを停止します。

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/stop?api-version=2022-07-31

要求が成功した場合は、 204 - No Content 応答が返されます。

次の要求を使用して、停止されたジョブを再開します。

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/resume?api-version=2022-07-31

要求が成功した場合は、 204 - No Content 応答が返されます。

次のコマンドを使用して、障害が発生したデバイス上の既存のジョブを再実行します。

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/rerun/rerun-001?api-version=2022-07-31

スケジュールされたジョブを作成する

スケジュールされたジョブのペイロードは標準ジョブと似ていますが、次の追加フィールドが含まれます。

フィールド	説明
schedule/start	ジョブの開始日時 (ISO 8601 形式)
schedule/recurrence	`daily`、`monthly`、`yearly \|` のいずれか。
schedule/end	ジョブの繰り返し回数または終了日 (ISO 8601 形式) を指定する省略可能なフィールド

PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

次の例は、スケジュールされたジョブを作成する要求本文を示しています。

{
    "displayName": "New Scheduled Job",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    }
}

この要求に対する応答は、次の例のようになります。

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

スケジュールされたジョブを取得する

スケジュールされたジョブを取得するには、次の要求を使用します。

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

スケジュール済みジョブの一覧を取得

スケジュールされたジョブの一覧を取得するには、次の要求を使用します。

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "id": "scheduled-Job-001",
            "displayName": "New Scheduled Job",
            "description": "",
            "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
                    "path": "Company",
                    "value": "Contoso"
                }
            ],
            "schedule": {
                "start": "2022-10-24T22:29:01Z",
                "recurrence": "daily"
            },
            "enabled": false,
            "completed": false,
            "etag": "\"88003877-0000-0700-0000-631020670000\""
        },
        {
            "id": "46480dff-dc22-4542-924e-a5d45bf347aa",
            "displayName": "test",
            "description": "",
            "group": "cdd04344-bb55-425b-a55a-954d68383289",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:rigado:evxfmi0xim",
                    "path": "test",
                    "value": 2
                }
            ],
            "schedule": {
                "start": "2022-09-01T03:00:00.000Z"
            },
            "enabled": true,
            "completed": true,
            "etag": "\"88000f76-0000-0700-0000-631020310000\""
        }
    ]
}

スケジュールされたジョブを更新する

スケジュールされたジョブを更新するには、次の要求を使用します。

PATCH https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

次の例は、スケジュールされたジョブを更新する要求本文を示しています。

{
  "schedule": {
    "start": "2022-10-24T22:29:01Z",
    "recurrence": "weekly"
  }
}

この要求に対する応答は、次の例のようになります。

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "weekly"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

スケジュールされたジョブを削除する

スケジュールされたジョブを削除するには、次の要求を使用します。

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

次のステップ

REST API を使ってジョブを管理する方法を学んだら、次にお勧めの手順は「チュートリアル: REST API を使用して Azure IoT Central アプリケーションを管理する」方法を学ぶことです。

次の方法で共有

IoT Central REST API を使用してジョブの作成と管理を行う方法

ジョブペイロード

ジョブ情報の取得

ジョブの作成

ジョブの停止、再開、および再実行

スケジュールされたジョブを作成する

スケジュールされたジョブを取得する

スケジュール済みジョブの一覧を取得

スケジュールされたジョブを更新する

スケジュールされたジョブを削除する

次のステップ

フィードバック

その他のリソース

次の方法で共有

IoT Central REST API を使用してジョブの作成と管理を行う方法

ジョブ ペイロード

ジョブ情報の取得

ジョブの作成

ジョブの停止、再開、および再実行

スケジュールされたジョブを作成する

スケジュールされたジョブを取得する

スケジュール済みジョブの一覧を取得

スケジュールされたジョブを更新する

スケジュールされたジョブを削除する

次のステップ

フィードバック

その他のリソース

ジョブペイロード