Microsoft Azure IoT 设备预配客户端库（Python版）

导航

验证详情

这些详情已由PyPI验证
维护者
来自gravatar.com的microsoft头像 microsoft

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据
  • 许可协议： MIT 许可协议 (MIT 许可协议)
  • 作者： Microsoft Corporation
  • 标签 azure, azure sdk, iot, dps, device, provisioning
  • 要求： Python >=3.7
分类器

项目描述

Azure IoT 设备预配客户端库（Python版）

IoT 中心设备预配服务（DPS）是 IoT 中心的辅助服务，它允许无需人工干预即可进行零接触、即时预配到正确的 IoT 中心，从而使客户能够以安全和可扩展的方式预配数百万台设备。

此服务 SDK 为后端应用程序提供数据平面操作。您可以使用此服务 SDK 创建和管理单个注册和注册组，以及查询和管理设备注册记录。

了解如何使用我们的快速入门、教程和示例将设备预配到您的 IoT 中心。

入门

先决条件

此软件包已在 Python 3.7+ 上进行了测试。有关 Azure 库的完整视图，请参阅 azure sdk python 发布。

安装软件包

使用 pip 安装 Azure IoT 设备预配客户端库（Python）

pip install azure-iot-deviceprovisioning

创建 IoT Hub 设备预配服务

如果您想创建新的设备预配服务，可以使用 Azure CLI

# Create a new resource group (if necessary)
az group create --name my-resource-group --location westus2

# Create the DPS instance
az iot dps create --name my-dps --resource-group my-resource-group --location westus2

Azure 门户 或 Bicep

创建客户端

Azure IoT 设备预配客户端库（Python）允许您与三个主要操作类别进行交互：单个注册、注册组和设备注册状态。

与这些资源交互从 DeviceProvisioningClient 实例开始。要创建 DeviceProvisioningClient 对象，您需要 DPS 资源的端点 URL 和一个允许您访问资源的凭据。

从 Azure 凭据创建客户端

要使用 Azure Active Directory (AAD) 令牌凭据，请提供从 azure-identity 库获取的所需凭据类型的实例。例如，可以使用 DefaultAzureCredential 来验证客户端。

from azure.iot.deviceprovisioning import DeviceProvisioningClient
from azure.identity import DefaultAzureCredential

# Initialize credential object
credential = DefaultAzureCredential()

# Create client using endpoint and credential
client = DeviceProvisioningClient(endpoint="https://my-dps.azure-device-provisioning.net/", credential=credential)

使用 DPS 连接字符串

根据您的用例和授权方法，您可能更喜欢使用 DPS 连接字符串初始化客户端实例，而不是分别提供端点 URL 和凭据。为此，将 DPS 连接字符串传递给客户端的 from_connection_string 类方法。

from azure.iot.deviceprovisioning import DeviceProvisioningClient

connection_string = "Hostname=https;SharedAccessKeyName=xxxx;SharedAccessKey=xxxx"
client = DeviceProvisioningClient.from_connection_string(connection_string=connection_string)

使用 SAS 凭据

客户端实例还可以使用 DPS 资源的共享访问策略的各个组件以及从策略组件和 DPS 端点字符串生成的 SAS 令牌来初始化 AzureNamedKeyCredential。同样，也可以使用 AzureSasCredential。

from azure.iot.deviceprovisioning import DeviceProvisioningClient
from azure.iot.deviceprovisioning import generate_sas_token
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

dps_endpoint = "https://my-dps.azure-device-provisioning.net/"
policy_name = "<access_policy_name>"
policy_key = "<access_policy_primary_key>"


# AzureNamedKeyCredential
credential = AzureNamedKeyCredential(name=policy_name, key=policy_key)

# AzureSasCredential
sas_token = generate_sas_token(dps_endpoint, policy_name, policy_key)
credential = AzureSasCredential(signature=sas_token)

client = DeviceProvisioningClient(endpoint=dps_endpoint, credential=credential)

异步客户端

此库包含在 Python 3.5+ 上支持的完整异步 API。要使用它，您必须首先安装异步传输，例如 aiohttp。有关更多信息，请参阅 azure-core 文档。

关键概念

以下操作组构成了服务数据平面层

  1. 单个注册
  2. 注册组
  3. 设备注册

Azure IoT 设备预配客户端库（Python）允许您通过 DeviceProvisioningClient 上的不同操作命名空间与每个这些组件进行交互。

示例

以下部分提供了几个代码片段，涵盖了一些最常见的服务，包括

创建单个设备注册

创建对称密钥注册以预配单个设备并配置其初始状态。

from azure.iot.deviceprovisioning import DeviceProvisioningClient

# Initialize client
client = DeviceProvisioningClient.from_connection_string(connection_string="<connection_string>")

# Construct initial twin with desired properties of {"key": "value"} and a tag of {"env": "Development"}
initial_twin = {
    "properties": {
        "desired": {
            "key": "value"
        }
    },
    "tags": {
        "env": "Development"
    }
}

# Create a symmetric key individual enrollment with initial twin
client.individual_enrollment.create_or_update(
    id="<enrollment_id>",
    enrollment = {
        "registrationId": "<enrollment_id>",
        "attestation": {
            "type": "symmetricKey",
        },
        "deviceId": "<device_id>",
        "initialTwin": initial_twin
    }
)

创建具有重置策略的注册

创建具有特定重置策略的注册。

from azure.iot.deviceprovisioning import DeviceProvisioningClient

# Initialize client
client = DeviceProvisioningClient.from_connection_string(connection_string="<connection_string>")

# Create a reprovisioning policy to migrate the device's data and reassess hub assignment
reprovision_policy = {
    "migrateDeviceData": True,
    "updateHubAssignment": True
}

# Create a symmetric key individual enrollment with reprovisioning policy
client.individual_enrollment.create_or_update(
    id="<enrollment_id>",
    enrollment = {
        "registrationId": "<enrollment_id>",
        "attestation": {
            "type": "symmetricKey",
        },
        "deviceId": "<device_id>",
        "reprovisionPolicy": reprovision_policy
    }
)

创建中间 x509 证书注册组

创建使用 x509 证明预配一个或多个设备的 x509 注册组。

from azure.iot.deviceprovisioning import DeviceProvisioningClient

# Initialize client
client = DeviceProvisioningClient.from_connection_string(connection_string="<connection_string>")

# Load certificate contents
certificate = open("certificate.pem", "rt", encoding="utf-8")
cert_contents = certificate.read()

# Create x509 enrollment group with an intermediate cert
client.enrollment_groups.create_or_update(
    id="<enrollment_group_id>",
    enrollment_group={
        "enrollmentGroupId": "<enrollment_group_id>",
        "attestation": {
            "type": "x509",
            "x509": {
                "signingCertificates": {
                    "primary": {"certificate": f"{cert_contents}"},
                    "secondary": {"certificate": f"{cert_contents}"},
                }
            },
        },
    }
)

创建 x509 CA 证书注册组

创建具有 x509 CA 证书证明的注册组。这将确保已注册设备的证书链已由目标 CA 证书在控制平面层签名。

from azure.iot.deviceprovisioning import DeviceProvisioningClient

# Initialize client
client = DeviceProvisioningClient.from_connection_string(connection_string="<connection_string>")

# Load certificate contents
ca_certificate = open("ca_certificate.pem", "rt", encoding="utf-8")
ca_contents = certificate.read()

# Create x509 enrollment group with CA References
client.enrollment_groups.create_or_update(
    id="<enrollment_group_id>",
    enrollment_group={
        "enrollmentGroupId": "<enrollment_group_id>",
        "attestation": {
            "type": "x509",
            "x509": {
                "caReferences": {
                    "primary": f"{ca_contents}",
                    "secondary": f"{ca_contents}",
                }
            },
        },
    }
)

检查设备注册状态

from azure.iot.deviceprovisioningservice import DeviceProvisioningClient

# Initialize client
client = DeviceProvisioningClient.from_connection_string(connection_string="<connection_string>")

# Query device registrations for an enrollment group
device_registrations = client.device_registration_state.query(
    id="<enrollment_group_id>"
)

# Get device registration status for a particular device
state = client.device_registration_state.get(
    id="<device_id>"
)

故障排除

连接字符串错误

如果您看到错误消息表明 IoT DPS 连接字符串缺少属性：[属性]，这表明您的连接字符串格式不正确。

请确保您的连接字符串以分号分隔，并包含以下属性：hostname、sharedaccesskeyname 和 sharedaccesskey。

标准 HTTPResponse 错误

本SDK中的客户端方法在请求失败时抛出HttpResponseError。Azure IoT Hub设备预配客户端库抛出的HttpResponseError包括详细的错误响应信息，这些信息提供了对问题原因的深入了解，并包含了修复常见问题的纠正措施。

这些错误信息可以在HttpResponseError实例的message属性中找到。

以下是捕获和处理这些错误的一个示例

try:
    client.individual_enrollment.create_or_update(
        id="<enrollment_id>",
        enrollment = {
            "registrationId": "<enrollment_id>",
            "attestation": {
                "type": "symmetricKey",
            },
        }
    )
except HttpResponseError as error:
    # handle the error here
    if error.status_code == 409:
        pass

  • HTTP 400错误表示请求格式不正确或请求有误。请核实您的输入类型是否正确，以及是否已提供所有必需的属性。

  • HTTP 401错误表示认证问题。请检查异常消息或日志以获取更多信息。

  • HTTP 403错误表示提供的用户凭据没有权限在此设备预配服务资源上执行特定操作。这也可能发生在您错误生成了SAS凭据的情况下。请验证您的凭据并确保对您的DPS资源有访问权限。

  • HTTP 409错误表示资源冲突。这可能在以下情况下发生

    • 您尝试创建一个已存在的对象
    • 您使用不带eTag / if-match值的create_or_update_方法更新对象

下一步

更多示例代码

请参阅我们的示例。在示例目录中，您可以找到多个示例，包括异步示例。

  • 设备注册状态 (异步版本)

    • 创建基本注册组
    • 注册设备（需要设备SDK）
    • 查询注册组中的设备注册状态
    • 获取设备注册状态
    • 删除设备注册状态

  • 注册组 (异步版本)

    • 创建对称密钥注册组
    • 创建X509证书注册组
    • 获取注册组
    • 更新注册组
    • 获取注册组证明机制
    • 批量注册组操作
    • 删除注册组

  • 个人注册 (异步版本)

    • 创建对称密钥个人注册
    • 创建TPM证明个人注册
    • 创建X509证书个人注册
    • 获取个人注册
    • 更新个人注册
    • 获取个人注册的证明机制
    • 批量个人注册操作
    • 删除个人注册

附加文档

有关Azure IoT Hub设备预配服务的更详细文档，请参阅learn.microsoft.com上的Azure IoT Hub设备预配服务文档。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权并且确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人会自动确定您是否需要提供CLA，并适当地标记PR（例如，标签、评论）。只需遵循机器人提供的说明即可。您只需在所有使用我们CLA的仓库中做一次。

本项目采用了微软开源行为准则。如需更多信息，请参阅行为准则常见问题解答，或通过opencode@microsoft.com联系我们，提出任何额外的问题或意见。

发布历史

1.0.0b1 (2023-06-14)

  • 初始发布

项目详情

验证详情

这些详情已由PyPI验证
维护者
来自gravatar.com的microsoft头像 microsoft

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据
  • 许可协议： MIT 许可协议 (MIT 许可协议)
  • 作者： Microsoft Corporation
  • 标签 azure, azure sdk, iot, dps, device, provisioning
  • 要求： Python >=3.7
分类器

发布历史 发布通知 | RSS 源

本版本

1.0.0b1 预发布

下载文件

下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。

源代码分发

azure-iot-deviceprovisioning-1.0.0b1.zip (146.7 kB 查看哈希值)

上传时间 源代码

构建分发

azure_iot_deviceprovisioning-1.0.0b1-py3-none-any.whl (88.3 kB 查看哈希值)

上传时间 Python 3

支持