Cihazları yönetmek için IoT Central REST API'sini kullanma

  • Makale

IoT Central REST API,IoT Central uygulamalarıyla tümleşen istemci uygulamaları geliştirmenizi sağlar. IoT Central uygulamanızdaki cihazları yönetmek için REST API'yi kullanabilirsiniz.

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.

İpucu

Postman'i kullanarak bu makalede açıklanan REST API çağrılarını deneyebilirsiniz. IoT Central Postman koleksiyonunu indirin ve Postman'a aktarın. Koleksiyonda, uygulamanızın alt etki alanı ve yönetici belirteci gibi değişkenleri ayarlamanız gerekir.

IoT Central kullanıcı arabirimini kullanarak cihazları yönetmeyi öğrenmek için bkz . Azure IoT Central uygulamanızda tek tek cihazları yönetme.

Cihazlar REST API'si

IoT Central REST API şunları yapmanızı sağlar:

  • Uygulamanıza cihaz ekleme
  • Uygulamanızdaki bir cihazı güncelleştirme
  • Uygulamanıza cihazların listesini alma
  • Kimliğe göre cihaz alma
  • Cihaz kimlik bilgilerini alma
  • Uygulamanızdaki bir cihazı silme
  • Uygulamadaki cihazların listesini filtreleme

Cihaz ekleme

Yeni bir cihaz oluşturmak için aşağıdaki isteği kullanın.

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

Aşağıdaki örnekte, bir cihaz şablonu için cihaz ekleyen bir istek gövdesi gösterilmektedir. Ayrıntıları IoT Central uygulama kullanıcı arabirimindeki cihaz şablonları sayfasından alabilirsiniz template .

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

İstek gövdesinde bazı gerekli alanlar vardır:

  • @displayName: Cihazın görünen adı.
  • @enabled: Bu nesnenin bir arabirim olduğunu bildirir.
  • @etag: Cihaz güncelleştirmelerinde çakışmayı önlemek için kullanılan ETag.
  • simulated: Cihaz simülasyonu yapılmış mı?
  • template : Cihazın cihaz şablonu tanımı.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Cihaz alma

Uygulamanızdan bir cihazın ayrıntılarını almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Not

Fareyi deviceId bir cihazın üzerine getirerek IoT Central Uygulama kullanıcı arabiriminden öğesini alabilirsiniz.

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

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Aşağıdaki tabloda, kullanıcı arabirimindeki bir cihazın durum değerinin REST API tarafından cihazlarla etkileşime geçmek için kullanılan değerlerle nasıl eşlediği gösterilmektedir:

KULLANıCı Arabirimi Cihazı durumu Notlar REST API Get
Onay bekleniyor Cihaz bağlantı grubunda otomatik onaylama seçeneği devre dışı bırakılır ve cihaz kullanıcı arabirimi aracılığıyla eklenmez.
Kullanıcının kullanılabilmesi için önce kullanıcı arabirimi aracılığıyla cihazı el ile onaylaması gerekir.		 Provisioned: false
Enabled: false
Kayıtlı Bir cihaz otomatik olarak veya el ile onaylandı. Provisioned: false
Enabled: true
Sağlanan Cihaz sağlandı ve IoT Central uygulamanıza bağlanabilir. Provisioned: true
Enabled: true
Engellendi Cihazın IoT Central uygulamanıza bağlanmasına izin verilmez. Diğer durumlardan herhangi birinde bulunan bir cihazı engelleyebilirsiniz. Provisioned: bağlı Waiting for approval/Registered/Provisioned status
Enabled: false

Cihaz kimlik bilgilerini alma

Uygulamanızdan bir cihazın kimlik bilgilerini almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

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

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

Cihazı güncelleştirme

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Aşağıdaki örnek istek gövdesi alanı olarak enabledfalsedeğiştirir:

{
  "enabled": false
}

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

Cihazı silme

Bir cihazı silmek için aşağıdaki isteği kullanın:

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Cihazları listeleyin

Uygulamanızdan cihazların listesini almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Dağıtım bildirimi atama

IoT Edge cihazı ekliyorsanız, cihaza bir IoT Edge dağıtım bildirimi atamak için API'yi kullanabilirsiniz. Daha fazla bilgi edinmek için bkz . Cihaza dağıtım bildirimi atama.

ODATA filtrelerini kullanma

API'nin ()api-version=2022-10-31-preview önizleme sürümünde, liste cihazları API'sinin döndürdiği sonuçları filtrelemek ve sıralamak için ODATA filtrelerini kullanabilirsiniz.

maxpagesize

Sonuç boyutunu ayarlamak için maxpagesize değerini kullanın. Döndürülen sonuç boyutu üst sınırı 100 ve varsayılan boyut 25'tir.

Uygulamanızdan ilk 10 cihazı almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

Yanıt, sonraki sonuç sayfasını almak için kullanabileceğiniz bir nextLink değeri içerir.

filtrele

Cihaz listesini filtreleyen ifadeler oluşturmak için filtreyi kullanın. Aşağıdaki tabloda kullanabileceğiniz karşılaştırma işleçleri gösterilmektedir:

Karşılaştırma İşleci Simge Örnek
Eşittir eşittir id eq 'device1' and scopes eq 'redmond'
Eşit Değil ne Enabled ne true
Küçüktür veya eşittir le id le '26whl7mure6'
Küçüktür lt id lt '26whl7mure6'
Büyüktür veya eşittir ge id ge '26whl7mure6'
Büyüktür gt id gt '26whl7mure6'

Aşağıdaki tabloda, filtre ifadelerinde kullanabileceğiniz mantıksal işleçler gösterilmektedir:

Mantıksal İşleç Simge Örnek
AND ve id eq 'device1' and enabled eq true
VEYA veya id eq 'device1' or simulated eq false

Filtre şu anda aşağıdaki cihaz alanlarıyla çalışır:

Fieldname Type Veri Akışı Açıklaması
id Dize Cihaz Kimliği
displayName Dize Cihaz görünen adı
enabled boolean Cihaz etkin durumu
provisioned boolean Cihaz sağlama durumu
simulated boolean Cihaz simülasyon durumu
template Dize Cihaz şablonu kimliği
scopes Dize kuruluş kimliği

filtre desteklenen işlevler:

Şu anda cihaz listeleri için desteklenen tek filtre işlevi şu işlevdir contains :

filter=contains(displayName, 'device1')

Aşağıdaki örnekte görünen adın dizesini thermostatiçerdiği tüm cihazların nasıl alınacağı gösterilmektedir:

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Orderby

Sonuçları sıralamak için orderby kullanın. Şu anda orderbyyalnızca displayName üzerinde sıralama yapmanıza olanak tanır. Varsayılan olarak, orderby artan düzende sıralar. Azalan düzende sıralamak için desc kullanın, örneğin:

orderby=displayName
orderby=displayName desc

Aşağıdaki örnekte, sonucun ölçütüne displayName göre sıralandığı tüm cihaz şablonlarının nasıl alınacağı gösterilmektedir:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

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

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

ayrıca iki veya daha fazla filtreyi birleştirebilirsiniz.

Aşağıdaki örnekte görünen adın dizesini Thermostatiçerdiği ilk üç cihazın nasıl alınacağı gösterilmektedir.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

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

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

Cihaz grupları

Bir IoT Central uygulamasında toplama verilerini izlemek, işlerle kullanmak ve erişimi yönetmek için cihaz grupları oluşturabilirsiniz. Cihaz grupları, gruba eklenecek cihazları seçen bir filtre tarafından tanımlanır. IoT Central portalında veya API'yi kullanarak cihaz grupları oluşturabilirsiniz.

Cihaz grubu ekleme

Yeni bir cihaz grubu oluşturmak için aşağıdaki isteği kullanın.

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

Bir cihaz grubu oluşturduğunuzda, gruba eklenecek cihazları seçen bir filter tanımlarsınız. A filter , bir cihaz şablonunu ve eşleşecek özellikleri tanımlar. Aşağıdaki örnek, özelliğin trueolduğu provisioned "dtmi:modelDefinition:dtdlv2" şablonuyla ilişkili 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",
  "organizations": [
    "seattle"
  ]
}

İstek gövdesinde bazı gerekli alanlar vardır:

  • @displayName: Cihaz grubunun görünen adı.
  • @filter: Bu grupta olması gereken cihazları tanımlayan sorgu.
  • @etag: Cihaz güncelleştirmelerinde çakışmayı önlemek için kullanılan ETag.
  • description: Cihaz grubunun kısa özeti.

Kuruluşlar alanı yalnızca bir uygulamanın kuruluş hiyerarşisi tanımlandığında kullanılır. Kuruluşlar hakkında daha fazla bilgi edinmek için bkz . IoT Central kuruluşlarını yönetme.

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",
  "organizations": [
    "seattle"
  ]
}

Cihaz grubu alma

Uygulamanızdan bir cihaz grubunun ayrıntılarını almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31
  • deviceGroupId - Cihaz grubu için benzersiz kimlik.

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

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Cihaz grubunu güncelleştirme

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

Örnek istek gövdesi, cihaz grubunun güncelleştirmesini displayName sağlayan aşağıdaki örneğe benzer:

{
  "displayName": "New group name"
}

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

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Cihaz grubunu silme

Bir cihaz grubunu silmek için aşağıdaki isteği kullanın:

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

Cihaz gruplarını listeleme

Uygulamanızdan cihaz gruplarının listesini almak için aşağıdaki isteği kullanın:

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

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

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

Kayıt grupları

Kayıt grupları, IoT Central uygulamanızdaki cihaz kimlik doğrulama seçeneklerini yönetmek için kullanılır. Daha fazla bilgi edinmek için bkz . IoT Central'da cihaz kimlik doğrulaması kavramları.

Kullanıcı arabiriminde kayıt grupları oluşturmayı ve yönetmeyi öğrenmek için bkz . X.509 sertifikalarına sahip cihazları IoT Central Uygulamasına bağlama.

Kayıt grubu oluşturma

X.509 sertifikalarını kullanan cihazlar için bir kayıt grubu oluşturduğunuzda, önce kök veya ara sertifikayı IoT Central uygulamanıza yüklemeniz gerekir.

Kök ve cihaz sertifikaları oluşturma

Bu bölümde, bir cihazı IoT Central'a bağlamak için ihtiyacınız olan X.509 sertifikalarını oluşturacaksınız.

Uyarı

X.509 sertifikaları oluşturmanın bu yolu yalnızca test içindir. Bir üretim ortamı için sertifika oluşturma için resmi, güvenli mekanizmanızı kullanmalısınız.

  1. İndirdiğiniz Node.js için Microsoft Azure IoT SDK'sında sertifika oluşturucu betiğine gidin. Gerekli paketleri yükleyin:

    cd azure-iot-sdk-node/provisioning/tools
npm install

  2. Bir kök sertifika oluşturun ve betiği çalıştırarak bir cihaz sertifikası türetin:

    node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert

    İpucu

    Cihaz kimliği harf, sayı ve - karakter içerebilir.

Bu komutlar aşağıdaki kök ve cihaz sertifikalarını oluşturur:

filename Içeriği
mytestrootcert_cert.pem Kök X.509 sertifikasının genel bölümü
mytestrootcert_key.pem Kök X.509 sertifikasının özel anahtarı
mytestrootcert_fullchain.pem Kök X.509 sertifikası için anahtar zincirinin tamamı.
mytestrootcert.pfx Kök X.509 sertifikası için PFX dosyası.
sampleDevice01_cert.pem Cihaz X.509 sertifikasının genel bölümü
sampleDevice01_key.pem Cihaz X.509 sertifikasının özel anahtarı
sampleDevice01_fullchain.pem Cihaz X.509 sertifikası için tüm anahtarlık.
sampleDevice01.pfx Cihaz X.509 sertifikası için PFX dosyası.

Bu dosyaların konumunu not edin. Daha sonra lazım olacak.

Kök sertifikanın base-64 kodlanmış sürümünü oluşturma

Yerel makinenizde oluşturduğunuz sertifikaları içeren klasörde convert.js adlı bir dosya oluşturun ve aşağıdaki JavaScript içeriğini ekleyin:

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

Sertifikanın base-64 kodlama sürümünü oluşturmak için aşağıdaki komutu çalıştırın:

node convert.js mytestrootcert_cert.pem

Sertifikanın base-64 kodlanmış sürümünü not edin. Daha sonra lazım olacak.

X.509 kayıt grubu ekleme

Kimlik olarak yeni myx509eg bir kayıt grubu oluşturmak için aşağıdaki isteği kullanın:

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

Aşağıdaki örnekte yeni bir X.509 kayıt grubu ekleyen bir istek gövdesi gösterilmektedir:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

İstek gövdesinde bazı gerekli alanlar vardır:

  • @displayName: Kayıt grubunun görünen adı.
  • @enabled: Grubu kullanan cihazların IoT Central'a bağlanmasına izin verilip verilmeyeceği.
  • @type: Grup aracılığıyla bağlanan cihazların türü veya iotiotEdge.
  • attestation: Kayıt grubu için kanıtlama mekanizması veya symmetricKeyx509.

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

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

Kayıt grubuna X.509 sertifikası ekleme

myx509eg kayıt grubunun birincil X.509 sertifikasını ayarlamak için aşağıdaki isteği kullanın:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Kayıt grubuna birincil veya ikincil X.509 sertifikası eklemek için bu isteği kullanın.

Aşağıdaki örnekte bir kayıt grubuna X.509 sertifikası ekleyen bir istek gövdesi gösterilmektedir:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}
  • certificate - Daha önce not aldığınız sertifikanın taban-64 sürümü.
  • doğrulandı - true sertifikanın geçerli olduğunu doğrularsanız, false sertifikanın geçerliliğini kanıtlamanız gerekiyorsa.

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

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

X.509 sertifikası için doğrulama kodu oluşturma

Bir kayıt grubunun birincil veya ikincil X.509 sertifikası için doğrulama kodu oluşturmak için aşağıdaki isteği kullanın.

Önceki istekte olarak ayarladıysanız verifiedfalse , kayıt grubundaki birincil X.509 sertifikası myx509eg için bir doğrulama kodu oluşturmak için aşağıdaki isteği kullanın:

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

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

{
  "verificationCode": "<certificate-verification-code>"
}

Doğrulama kodunu not edin, sonraki adımda bu koda ihtiyacınız vardır.

Doğrulama sertifikasını oluşturma

Önceki adımda doğrulama kodundan bir doğrulama sertifikası oluşturmak için aşağıdaki komutu kullanın:

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

Sertifikanın base-64 kodlanmış sürümünü oluşturmak için aşağıdaki komutu çalıştırın:

node convert.js verification_cert.pem

Sertifikanın base-64 kodlanmış sürümünü not edin. Daha sonra lazım olacak.

Kayıt grubunun X.509 sertifikalarını doğrulama

Sertifikaya imzalı doğrulama kodunu sağlayarak kayıt grubunun birincil X.509 sertifikasını myx509eg doğrulamak için aşağıdaki isteği kullanın:

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

Aşağıdaki örnekte X.509 sertifikasını doğrulayan bir istek gövdesi gösterilmektedir:

{
  "certificate": "base64-verification-certificate"
}

Kayıt grubunun X.509 sertifikalarını alma

Uygulamanızdan bir kayıt grubunun X.509 sertifikasının ayrıntılarını almak için aşağıdaki isteği kullanın:

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

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

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Kayıt grubundan X.509 sertifikası silme

Kimliği myx509egolan bir kayıt grubundan birincil X.509 sertifikasını silmek için aşağıdaki isteği kullanın:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Kayıt grubu alma

Kimlik olarak bir mysymmetric kayıt grubunun ayrıntılarını almak için aşağıdaki isteği kullanın:

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

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Kayıt grubunu güncelleştirme

Bir kayıt grubunu güncelleştirmek için aşağıdaki isteği kullanın.

PATCH https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Aşağıdaki örnekte, kayıt grubunun görünen adını güncelleştiren bir istek gövdesi gösterilmektedir:

{
  "displayName": "My new group name",
}

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

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Kayıt grubunu silme

Kimliği myx509egolan bir kayıt grubunu silmek için aşağıdaki isteği kullanın:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Kayıt gruplarını listeleme

Uygulamanızdan kayıt gruplarının listesini almak için aşağıdaki isteği kullanın:

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

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

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}