İşleri oluşturmak yönetmek için IoT Central REST API kullanma

Makale
10/22/2024

IoT Central REST API,IoT Central uygulamalarıyla tümleşen istemci uygulamaları geliştirmenizi sağlar. IoT Central uygulamanızda iş oluşturmak ve yönetmek için REST API'yi kullanabilirsiniz. REST API şunları yapmanızı sağlar:

Uygulamanızdaki işleri listeleyin ve iş ayrıntılarını görüntüleyin.
Uygulamanızda iş oluşturun.
Uygulamanızda işleri durdurun, sürdürin ve yeniden çalıştırın.
İşleri zamanlayın ve uygulamanızda zamanlanmış iş ayrıntılarını görüntüleyin.

Zamanlanmış işler, gelecekteki bir zamanda çalıştırılacak şekilde oluşturulur. Zamanlanmış bir işin bir kerelik, günlük veya haftalık olarak çalışması için bir başlangıç tarihi ve saati ayarlayabilirsiniz. Zamanlanmamış işler yalnızca bir kerelik çalışır.

Bu makalede, cihazları toplu olarak denetlemek için API'nin /jobs/{job_id} nasıl kullanılacağı açıklanmaktadır. Cihazları tek tek de denetleyebilirsiniz.

Her IoT Central REST API çağrısı bir yetkilendirme üst bilgisi gerektirir. Daha fazla bilgi edinmek için bkz . IoT Central REST API çağrılarının kimliğini doğrulama ve yetkilendirme.

IoT Central REST API'sinin başvuru belgeleri için bkz . Azure IoT Central REST API başvurusu.

Kullanıcı arabiriminde iş oluşturmayı ve yönetmeyi öğrenmek için bkz . Azure IoT Central uygulamanızda cihazları toplu olarak yönetme.

İş yükleri

Bu makalede açıklanan API'lerin çoğu aşağıdaki JSON kod parçacığına benzeyen bir tanım içerir:

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

Aşağıdaki tabloda, önceki JSON kod parçacığındaki alanlar açıklanmaktadır:

Alan	Açıklama
`id`	Uygulamanızdaki işin benzersiz kimliği.
`displayName`	Uygulamanızdaki işin görünen adı.
`description`	İşin açıklaması.
`group`	İşin uygulandığı cihaz grubunun kimliği. Uygulamanızdaki cihaz gruplarının `deviceGroups` listesini almak için önizleme REST API'sini kullanın.
`status`	İşin durumu . `complete`, , `cancelled`, `failed`, `pending`, `running`. `stopped`
`batch`	Varsa, bu bölüm işteki cihazların nasıl toplu iş yapılacağını tanımlar.
`batch/type`	Her toplu işlemin `percentage` boyutu, gruptaki toplam cihazlardan veya cihazlardan oluşan bir `number` boyuta sahiptir.
`batch/value`	Cihazların yüzdesi veya her toplu işlemdeki cihaz sayısı.
`cancellationThreshold`	Varsa, bu bölüm işin iptal eşiğini tanımlar.
`cancellationThreshold/batch`	`true` veya `false`. True ise, her toplu iş için iptal eşiği ayarlanır. ise `false`, iptal eşiği tüm iş için geçerlidir.
`cancellationThreshold/type`	İş için iptal eşiği bir veya bir `number` cihazdır`percentage`.
`cancellationThreshold/value`	Cihazların yüzdesi veya iptal eşiğini tanımlayan cihaz sayısı.
`data`	İşin gerçekleştirdiği işlem dizisi.
`data/type`	`PropertyJobData`, , `CommandJobDataCloudPropertyJobData`veya `DeviceTemplateMigrationJobData`. API'nin önizleme sürümü içerir `DeviceManifestMigrationJobData`.
`data/target`	Hedef cihazların model kimliği.
`data/path`	Özelliğin, komutun veya bulut özelliğinin adı.
`data/value`	Ayarlanacağı özellik değeri veya gönderilecek komut parametresi.

İş bilgilerini alma

Uygulamanızdaki işlerin listesini almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Kimliğine göre tek bir işi almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Bir işteki cihazların ayrıntılarını almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

İş oluşturma

İş oluşturmak için aşağıdaki isteği kullanın:

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

group İstek gövdesindeki alan, IoT Central uygulamanızdaki bir cihaz grubunu tanımlar. bir iş, işin üzerinde çalıştığı cihaz kümesini tanımlamak için bir cihaz grubu kullanır.

Henüz uygun bir cihaz grubunuz yoksa REST API çağrısıyla bir grup oluşturabilirsiniz. Aşağıdaki örnek, grup kimliği olarak ile group1 bir cihaz grubu oluşturur:

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

Bir cihaz grubu oluşturduğunuzda, gruba eklenecek cihazları seçen bir filter tanımlarsınız. Filtre, bir cihaz şablonunu ve eşleşecek özellikleri tanımlar. Aşağıdaki örnek, özelliğinin trueolduğu provisioned "dtmi:modelDefinition:dtdlv2" cihaz şablonuyla ilişkilendirilmiş tüm cihazları içeren cihaz grubu oluşturur.

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Artık yanıttan id alınan değeri kullanarak yeni bir iş oluşturabilirsiniz.

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

Bu isteğin yanıtı aşağıdaki örneğe benzer. İlk iş durumu: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"
}

İşleri durdurma, sürdürme ve yeniden çalıştırma

Çalışan bir işi durdurmak için aşağıdaki isteği kullanın:

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

İstek başarılı olursa bir 204 - No Content yanıt döndürür.

Durdurulmuş bir işi sürdürmek için aşağıdaki isteği kullanın:

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

İstek başarılı olursa bir 204 - No Content yanıt döndürür.

Başarısız olan cihazlarda var olan bir işi yeniden çalıştırmak için aşağıdaki komutu kullanın:

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

Zamanlanmış iş oluşturma

Zamanlanmış bir işin yükü standart bir işe benzer ancak aşağıdaki ek alanları içerir:

Alan	Açıklama
zamanlama/başlangıç	iso 8601 biçiminde işin başlangıç tarihi ve saati
zamanlama/yinelenme	, , `monthly`' lerden `daily`biri`yearly \|`
zamanlama/bitiş	İş için yineleme sayısını veya ISO 8601 biçiminde bir bitiş tarihini belirten isteğe bağlı bir alan

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

Aşağıdaki örnek, zamanlanmış bir iş oluşturan bir istek gövdesini gösterir.

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "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\""
}

Zamanlanmış iş alma

Zamanlanmış bir iş almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "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\""
}

Zamanlanmış işleri listeleme

Zamanlanmış işlerin listesini almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Zamanlanmış işi güncelleştirme

Zamanlanmış bir işi güncelleştirmek için aşağıdaki isteği kullanın:

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

Aşağıdaki örnek, zamanlanmış işi güncelleştiren bir istek gövdesini gösterir.

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "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\""
}

Zamanlanmış işi silme

Zamanlanmış bir işi silmek için aşağıdaki isteği kullanın

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

Sonraki adımlar

REST API ile işleri yönetmeyi öğrendiğinize göre, önerilen bir sonraki adım öğretici: Azure IoT Central uygulamasını yönetmek için REST API'yi kullanma hakkında bilgi edinmektir.

Aracılığıyla paylaş

İşleri oluşturmak yönetmek için IoT Central REST API kullanma

İş yükleri

İş bilgilerini alma

İş oluşturma

İşleri durdurma, sürdürme ve yeniden çalıştırma

Zamanlanmış iş oluşturma

Zamanlanmış iş alma

Zamanlanmış işleri listeleme

Zamanlanmış işi güncelleştirme

Zamanlanmış işi silme

Sonraki adımlar

Geri Bildirim

Ek kaynaklar