IoT Central REST API çağrılarının kimliğini doğrulama ve yetkilendirme

  • Makale

IoT Central REST API,IoT Central uygulamalarıyla tümleşen istemci uygulamaları geliştirmenizi sağlar. IoT Central uygulamanızdaki cihaz şablonları, cihazlar, işler, kullanıcılar ve roller gibi kaynaklarla çalışmak için REST API'yi kullanın.

Her IoT Central REST API çağrısı, Çağıranın kimliğini ve çağıranın uygulama içinde verilen izinleri belirlemek için IoT Central'ın kullandığı bir yetkilendirme üst bilgisi gerektirir.

Bu makalede, yetkilendirme üst bilgisinde kullanabileceğiniz belirteç türleri ve bunların nasıl alınabileceği açıklanmaktadır. Hizmet sorumluları, IoT Central REST API erişim yönetimi için önerilen yaklaşımdır.

Belirteç türleri

REST API kullanarak bir IoT Central uygulamasına erişmek için şunları kullanabilirsiniz:

  • Microsoft Entra taşıyıcı belirteci. Taşıyıcı belirteci bir Microsoft Entra kullanıcı hesabı veya hizmet sorumlusuyla ilişkilendirilir. Belirteç, çağırana kullanıcının veya hizmet sorumlusunun IoT Central uygulamasında sahip olduğu izinleri verir.
  • IoT Central API belirteci. API belirteci, IoT Central uygulamanızdaki bir rolle ilişkilendirilir.

REST API kullanan otomasyon ve betikleri geliştirirken ve test ederken kullanıcı hesabınızla ilişkili taşıyıcı belirteci kullanın. Üretim otomasyonu ve betikler için hizmet sorumlusuyla ilişkilendirilmiş taşıyıcı belirteci kullanın. Belirteçlerin süresi dolduğunda sızıntı ve sorun riskini azaltmak için API belirtecine tercih olarak taşıyıcı belirteci kullanın.

IoT Central'daki kullanıcılar ve roller hakkında daha fazla bilgi edinmek için bkz . IoT Central uygulamanızda kullanıcıları ve rolleri yönetme.

Taşıyıcı belirteci alma

Microsoft Entra kullanıcı hesabınız için taşıyıcı belirteç almak için aşağıdaki Azure CLI komutlarını kullanın:

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

Önemli

az login Cloud Shell kullanıyor olsanız bile komutu gereklidir.

Önceki komutun JSON çıkışı aşağıdaki örneğe benzer:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

Taşıyıcı belirteci yaklaşık bir saat geçerlidir ve bundan sonra yeni bir tane oluşturmanız gerekir.

Hizmet sorumlusu için taşıyıcı belirteci almak için bkz . Hizmet sorumlusu kimlik doğrulaması.

API belirteci alma

API belirteci almak için IoT Central kullanıcı arabirimini veya REST API çağrısını kullanabilirsiniz. Kök kuruluşla ilişkili Yönetici istrator'lar ve doğru role atanan kullanıcılar API belirteçleri oluşturabilir.

İpucu

API belirteçlerinde oluşturma ve silme işlemleri denetim günlüğüne kaydedilir.

IoT Central kullanıcı arabiriminde:

  1. İzinler API belirteçleri'ne >gidin.

  2. + Yeni veya API belirteci oluştur'u seçin.

  3. Belirteç için bir ad girin ve bir rol ve kuruluş seçin.

  4. Oluştur seçeneğini belirleyin.

  5. IoT Central aşağıdaki örneğe benzeyen belirteci görüntüler:

    SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

    Bu ekran, API belirtecini görebileceğiniz tek zamandır, kaybederseniz yeni bir belirteç oluşturmanız gerekir.

API belirteci yaklaşık bir yıl geçerlidir. IoT Central uygulamanızda hem yerleşik hem de özel roller için belirteçler oluşturabilirsiniz. API belirtecini oluştururken seçtiğiniz kuruluş, API'nin hangi cihazlara erişimi olduğunu belirler. Uygulamanıza kuruluş eklemeden önce oluşturulan tüm API belirteçleri kök kuruluşla ilişkilendirilir.

Erişimi iptal etmeniz gerekiyorsa IoT Central kullanıcı arabiriminde API belirteçlerini silebilirsiniz.

REST API kullanma:

  1. Uygulamanızdan rol kimliklerinin listesini almak için REST API'sini kullanın:

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

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

    {
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

  2. Bir rol için API belirteci oluşturmak için REST API'yi kullanın. Örneğin, işleç rolü için adlı operator-token bir API belirteci oluşturmak için:

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

    İstek gövdesi:

    {
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

    Önceki komutun yanıtı aşağıdaki JSON gibi görünür:

    {
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

    Bu yanıt, API belirtecine erişiminiz olan tek zamandır ve kaybederseniz yeni bir belirteç oluşturmanız gerekir.

Bir uygulamadaki API belirteçlerini listelemek ve silmek için REST API'yi kullanabilirsiniz.

Taşıyıcı belirteci kullanma

REST API çağrısı yaparken taşıyıcı belirteci kullanmak için yetkilendirme üst bilginiz aşağıdaki örneğe benzer:

Authorization: Bearer eyJ0eX...fNQ

API belirteci kullanma

REST API çağrısı yaparken API belirteci kullanmak için yetkilendirme üst bilginiz aşağıdaki örneğe benzer:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889