Öğretici: Azure IoT Central uygulamasını yönetmek için REST API kullanma

Bu öğreticide, Bir IoT Central uygulaması oluşturmak ve bunlarla etkileşim kurmak için Azure IoT Central REST API'sini nasıl kullanacağınız gösterilmektedir. Bu öğreticide, hızlı başlangıçlarda Web kullanıcı arabirimini kullanarak tamamladığınız adımların çoğunu tamamlamak için REST API kullanılır. Bu adımlar, akıllı telefonunuzdaki bir uygulamayı IoT Central'a bağlanan bir IoT cihazı olarak kullanmayı içerir.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

Önkoşullar

Bu öğreticideki adımları tamamlamak için şunları yapmanız gerekir:

• Etkin bir Azure aboneliği. Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

• Resmi uygulama mağazalarından birinden ücretsiz bir uygulama yükleyebileceğiniz bir Android veya iOS akıllı telefon.

Azure CLI

REST API çağrıları yapmak ve bazı REST API'lerinin yetkilendirme için kullandığı taşıyıcı belirteçleri oluşturmak için Azure CLI'yi kullanırsınız.

• Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz . Azure Cloud Shell'de Bash için hızlı başlangıç.

  

• CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

  • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz . Azure CLI ile oturum açma.

  • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

  • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

REST API'yi yetkilendirme

REST API'yi kullanabilmeniz için yetkilendirmeyi yapılandırmanız gerekir. Bu öğreticideki REST API çağrıları iki yetkilendirme türünden birini kullanır:

• öğesine erişim https://apps.azureiotcentral.comyetkisi veren taşıyıcı belirteci. IoT Central uygulamasında API belirteçleri oluşturmak için bu taşıyıcı belirtecini kullanırsınız.
• IoT Central uygulamanızdaki özelliklere erişim yetkisi veren yönetici ve işleç API'si belirteçleri. Bu öğreticideki API çağrılarının çoğu için bu belirteçleri kullanırsınız. Bu belirteçler yalnızca belirli bir IoT Central uygulamasına erişim yetkisi sağlar.

erişim yetkisi veren bir taşıyıcı belirteci oluşturmak için aşağıdaki Azure CLI komutlarını https://apps.azureiotcentral.comçalıştırın:

az account get-access-token --resource https://apps.azureiotcentral.com

Değeri not accessToken edin, öğreticinin ilerleyen bölümlerinde bu değeri kullanırsınız.

Kaynak grubu oluşturma

Bu öğreticide oluşturduğunuz IoT Central uygulamasını içeren bir kaynak grubu oluşturmak için Azure cli'yi kullanın:

az group create --name iot-central-rest-tutorial --location eastus

IoT Central uygulaması oluşturma

Bu öğreticide kullanılacak rastgele ada sahip bir IoT Central uygulaması oluşturmak için aşağıdaki komutu kullanın:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Uygulama adını not edin, bu öğreticinin ilerleyen bölümlerinde bu adı kullanacaksınız.

API belirteçleri oluşturma

IoT Central uygulamanızda uygulama API'leri belirteçleri oluşturmak için aşağıdaki veri düzlemi isteklerini kullanın. Bu öğreticideki isteklerden bazıları yönetici izinlerine sahip bir API belirteci gerektirir, ancak çoğu işleç izinlerini kullanabilir:

Azure CLI kullanarak çağrılan operator-token bir işleç belirteci oluşturmak için aşağıdaki komutu çalıştırın. Rol GUID'si, tüm IoT Central uygulamalarında işleç rolünün kimliğidir:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Komutun döndürdüğü işleç belirtecini not edin; öğreticinin ilerleyen bölümlerinde bu belirteci kullanırsınız. Belirteç gibi SharedAccessSignature sr=2...görünür.

Azure CLI kullanarak adlı admin-token bir yönetici belirteci oluşturmak için aşağıdaki komutu çalıştırın. Rol GUID'si, tüm IoT Central uygulamalarında yönetici rolünün kimliğidir:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Komutun döndürdüğü yönetici belirtecini not edin; öğreticinin ilerleyen bölümlerinde bu belirteci kullanırsınız. Belirteç gibi SharedAccessSignature sr=2...görünür.

Bu belirteçleri IoT central uygulamanızda görmek istiyorsanız uygulamayı açın ve Güvenlik > İzinleri API belirteçleri'ne >gidin.

Cihaz kaydetme

Bir cihazın bağlanabilmesi için önce IoT Central'a kaydetmeniz gerekir. Cihazınızı uygulamanıza kaydetmek ve cihaz kimlik bilgilerini almak için aşağıdaki istekleri kullanın. İlk istek, cihaz kimliği olarak phone-001 ile bir cihaz oluşturur:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Komutun döndürdüğü idScope ve primaryKey değerlerini not edin, bunları öğreticinin ilerleyen bölümlerinde kullanırsınız.

Cihaz sağlama ve bağlama

Akıllı telefonunuzda cihaz kimlik bilgilerini el ile girme gereğini önlemek için IoT central tarafından oluşturulan bir QR kodunu kullanabilirsiniz. QR kodu cihaz kimliğini, kimlik kapsamını ve birincil anahtarı kodlar. QR kodunu görüntülemek için:

1. Daha önce not aldığınız uygulama URL'sini kullanarak IoT central uygulamanızı açın.
2. IoT Central uygulamanızda Cihazlar > Telefonum uygulamasıNA > BAĞLAN > QR kodu'na gidin. Cihaz bağlanana kadar bu sayfayı açık tutun.

Kurulumu basitleştirmek için bu makalede ioT cihazı olarak IoT Tak Çalıştır akıllı telefon uygulaması kullanılır. Uygulama akıllı telefonun algılayıcılarından toplanan telemetri verilerini gönderir, IoT Central'dan çağrılan komutlara yanıt verir ve özellik değerlerini IoT Central'a raporlar.

Uygulamayı uygulama mağazalarından birinden akıllı telefonunuza yükleyin:

IoT Tak Çalıştır uygulamasını Iot Central uygulamanıza bağlamak için:

1. Akıllı telefonunuzda IoT PnP uygulamasını açın.

2. Hoş geldiniz sayfasında QR kodunu tara'yı seçin. Akıllı telefonun kamerasını QR koduna doğrultun. Ardından bağlantı kurulurken birkaç saniye bekleyin.

3. Uygulamanın telemetri sayfasında, uygulamanın IoT Central'a gönderdiği verileri görebilirsiniz. Günlükler sayfasında, cihazın bağlanıyor ve birkaç başlatma iletisi görebilirsiniz.

Cihazın artık sağlandığından emin olmak için REST API'sini kullanabilirsiniz:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Komutun döndürdüğü template değeri not edin; öğreticinin ilerleyen bölümlerinde bu değeri kullanırsınız.

Uygulamadaki cihaz şablonlarını yönetmek için REST API'yi kullanabilirsiniz. Örneğin, uygulamadaki cihaz şablonlarını görüntülemek için:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Cihazı sorgulama ve denetleme

Cihazlarınızdan telemetri sorgulamak için REST API'yi kullanabilirsiniz. Aşağıdaki istek, belirli bir cihaz şablonu kimliğini paylaşan tüm cihazlardan ivmeölçer verilerini döndürür:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

Cihaz özelliklerini okumak ve ayarlamak için REST API'yi kullanabilirsiniz. Aşağıdaki istek, cihazın uyguladığı Cihaz Bilgileri bileşeninden tüm özellik değerlerini döndürür:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Cihaz komutlarını çağırmak için REST API'yi kullanabilirsiniz. Aşağıdaki istek, akıllı telefonunuzun ışığını üç saniye boyunca iki kez etkinleştiren bir komut çağırır. Komutun çalışması için akıllı telefonunuzun ekranının IoT Tak Çalıştır uygulamasının görünür olması gerekir:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Kaynakları temizleme

Bu öğreticide kullandığınız IoT Central uygulamasını tamamladıysanız silebilirsiniz:

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial