azure.azcollection.azure_rm_iothub 模块 – 管理 Azure IoT 中心

注意

此模块是 azure.azcollection 集合（版本 3.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了这个集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install azure.azcollection。您需要更多要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定：azure.azcollection.azure_rm_iothub。

azure.azcollection 0.1.2 中新增

概要

  • 创建、删除 Azure IoT 中心。

要求

执行此模块的主机需要以下要求。

  • python >= 2.7

  • 执行此模块的主机必须通过 galaxy 安装 azure.azcollection 集合

  • 必须通过 pip 在执行 azure.azcollection 模块的主机上安装集合的 requirements.txt 中列出的所有 python 包

  • 完整安装说明可在 https://galaxy.ansible.com/azure/azcollection 中找到

参数

参数

注释

ad_user

字符串

Active Directory 用户名。当使用 Active Directory 用户而不是服务主体进行身份验证时使用。

adfs_authority_url

字符串

在 azure.azcollection 0.0.1 中添加

Azure AD 授权 URL。当使用用户名/密码进行身份验证，并且拥有自己的 ADFS 授权时使用。

api_profile

字符串

在 azure.azcollection 0.0.1 中添加

选择与 Azure 服务通信时使用的 API 配置文件。默认值 latest 适用于公共云；未来的值将允许与 Azure Stack 一起使用。

默认值： "latest"

append_tags

布尔值

用于控制 tags 字段是规范的还是仅附加到现有标签。

当为规范时，在 tags 参数中找不到的任何标签将从对象的元数据中删除。

选项

  • false

  • true ← (默认)

auth_source

字符串

在 azure.azcollection 0.0.1 中添加

控制用于身份验证的凭据的来源。

也可以通过 ANSIBLE_AZURE_AUTH_SOURCE 环境变量设置。

当设置为 auto（默认值）时，优先级为模块参数 -> env -> credential_file -> cli。

当设置为 env 时，凭据将从环境变量中读取

当设置为 credential_file 时，它将从 ~/.azure/credentials 读取配置文件。

当设置为 cli 时，凭据将来自 Azure CLI 配置文件。subscription_id 或环境变量 AZURE_SUBSCRIPTION_ID 可用于标识订阅 ID（如果存在多个），否则使用默认的 az cli 订阅。

当设置为 msi 时，主机必须是启用了 MSI 扩展的 Azure 资源。subscription_id 或环境变量 AZURE_SUBSCRIPTION_ID 可用于标识订阅 ID（如果资源被授予对多个订阅的访问权限），否则选择第一个订阅。

msi 在 Ansible 2.6 中添加。

选项

  • "auto" ← (默认)

  • "cli"

  • "credential_file"

  • "env"

  • "msi"

cert_validation_mode

字符串

在 azure.azcollection 0.0.1 中添加

控制 Azure 端点的证书验证行为。默认情况下，所有模块都将验证服务器证书，但是当使用 HTTPS 代理时或针对 Azure Stack 时，可能需要通过传递 ignore 来禁用此行为。也可以通过凭据文件配置文件或 AZURE_CERT_VALIDATION 环境变量设置。

选项

  • "ignore"

  • "validate"

client_id

字符串

Azure 客户端 ID。当使用服务主体或托管标识 (msi) 进行身份验证时使用。

也可以通过 AZURE_CLIENT_ID 环境变量设置。

cloud_environment

字符串

在 azure.azcollection 0.0.1 中添加

对于美国公共云以外的云环境，环境名称（由 Azure Python SDK 定义，例如，AzureChinaCloud、AzureUSGovernment）或元数据发现端点 URL（Azure Stack 所需）。也可以通过凭据文件配置文件或 AZURE_CLOUD_ENVIRONMENT 环境变量设置。

默认值： "AzureCloud"

disable_instance_discovery

布尔值

在 azure.azcollection 2.3.0 中添加

确定尝试身份验证时是否执行实例发现。将其设置为 true 将完全禁用实例发现和授权验证。此功能旨在用于无法访问元数据端点的情况，例如在私有云或 Azure Stack 中。实例发现的过程包括从 https://login.microsoft.com/ 检索授权元数据以验证授权。通过将此设置为 **True**，将禁用对授权的验证。因此，至关重要的是要确保配置的授权主机是有效且值得信任的。

通过凭据文件配置文件或 AZURE_DISABLE_INSTANCE_DISCOVERY 环境变量设置。

选项

  • false ← (默认)

  • true

enable_file_upload_notifications

布尔值

如果设置为 True，则启用文件上传通知。

选项

  • false

  • true

event_endpoint

字典

与事件中心兼容的终结点属性。

partition_count

整数

在与事件中心兼容的终结点中，用于接收设备到云消息的分区数。

请参阅 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#device-to-cloud-messages。

默认值为 2。

retention_time_in_days

整数

设备到云消息的保留时间（天）。

请参阅 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#device-to-cloud-messages。

默认值为 1。

identity

字典

此资源的标识。

type

字符串

托管标识的类型

选项

  • "SystemAssigned"

  • "UserAssigned"

  • "None" ← (默认)

user_assigned_identities

字典

用户分配的托管标识及其选项

默认值： {}

append

布尔值

如果标识列表必须附加到当前标识 (true)，或者如果它必须替换当前标识 (false)

选项

  • false

  • true ← (默认)

id

列表 / 元素=字符串

与此资源关联的用户分配 ID 列表

默认值： []

ip_filters

列表 / 元素=字典

配置规则，用于拒绝或接受来自特定 IPv4 地址的流量。

action

字符串 / 必需

此规则捕获的请求的所需操作。

选项

  • "accept"

  • "reject"

ip_mask

字符串 / 必需

一个字符串，包含规则的 CIDR 表示法中的 IP 地址范围。

name

字符串 / 必需

筛选器的名称。

location

字符串

IoT 中心的位置。

log_mode

字符串

父参数。

log_path

字符串

父参数。

name

字符串 / 必需

IoT 中心的名称。

password

字符串

Active Directory 用户密码。当使用 Active Directory 用户而不是服务主体进行身份验证时使用。

profile

字符串

在 ~/.azure/credentials 文件中找到的安全配置文件。

resource_group

字符串 / 必需

资源组的名称。

routes

列表 / 元素=字典

将设备到云的消息路由到面向服务的终结点。

condition

字符串

路由查询的查询表达式，该表达式针对消息应用程序属性、系统属性、消息正文、设备孪生标签和设备孪生属性运行，以确定是否与终结点匹配。

有关构建查询的详细信息，请参阅 https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-routing-query-syntax

enabled

布尔值 / 必需

是否启用路由。

选项

  • false

  • true

endpoint_name

字符串 / 必需

IoT 中心将与查询匹配的消息发送到的 routing_endpoints 中的终结点的名称。

name

字符串 / 必需

路由的名称。

source

字符串 / 必需

要对其执行操作的数据流的源。

选项

  • "device_messages"

  • "twin_change_events"

  • "device_lifecycle_events"

  • "device_job_lifecycle_events"

routing_endpoints

列表 / 元素=字典

自定义终结点。

connection_string

字符串 / 必需

自定义终结点的连接字符串。

连接字符串应具有发送权限。

container_name

别名：container

字符串

当 resource_type=storage 时，自定义终结点的容器名称。

encoding

字符串

当 resource_type=storage 时，消息的编码。

name

字符串 / 必需

自定义终结点的名称。

resource_group

字符串

终结点的资源组。

默认值与 resource_group 相同。

resource_type

字符串 / 必需

自定义终结点的资源类型。

选项

  • "eventhub"

  • "queue"

  • "storage"

  • "topic"

subscription

字符串

终结点的订阅 ID。

默认值与 subscription 相同。

secret

字符串

Azure 客户端密码。当使用服务主体进行身份验证时使用。

sku

字符串

Azure IoT 中心的定价层。

请注意，每个订阅中只允许一个免费的 IoT 中心实例。如果免费实例超过一个，则会抛出异常。

创建时的默认值为 s1。

选项

  • "b1"

  • "b2"

  • "b3"

  • "f1"

  • "s1"

  • "s2"

  • "s3"

state

字符串

IoT 中心的状态。使用 present 创建或更新 IoT 中心，使用 absent 删除 IoT 中心。

选项

  • "absent"

  • "present" ← (默认)

subscription_id

字符串

你的 Azure 订阅 ID。

tags

字典

要作为元数据分配给对象的 string:string 对的字典。

对象上的元数据标记将使用任何提供的值进行更新。

要删除标记，请将 append_tags 选项设置为 false。

目前，Azure DNS 区域和流量管理器服务也不允许在标记中使用空格。

Azure Front Door 不支持使用

Azure Automation 和 Azure CDN 仅支持资源上的 15 个标记。

tenant

字符串

Azure 租户 ID。当使用服务主体进行身份验证时使用。

thumbprint

字符串

在 azure.azcollection 1.14.0 中添加

x509_certificate_path 中指定的私钥的指纹。

当使用服务主体进行身份验证时使用。

如果定义了 x509_certificate_path，则为必需项。

unit

整数

IoT 中心中的单元。

默认值为 1。

x509_certificate_path

路径

在 azure.azcollection 1.14.0 中添加

用于以 PEM 格式创建服务主体的 X509 证书的路径。

证书必须附加到私钥。

当使用服务主体进行身份验证时使用。

注释

注意

  • 要使用 Azure 进行身份验证，你可以传递参数、设置环境变量、使用存储在 ~/.azure/credentials 中的配置文件，或者在运行任务或 playbook 之前使用 az login 登录。

  • 也可以使用服务主体或 Active Directory 用户进行身份验证。

  • 要通过服务主体进行身份验证，请传递 subscription_id、client_id、secret 和 tenant，或者设置环境变量 AZURE_SUBSCRIPTION_ID、AZURE_CLIENT_ID、AZURE_SECRET 和 AZURE_TENANT。

  • 要通过 Active Directory 用户进行身份验证，请传递 ad_user 和 password，或者在环境中设置 AZURE_AD_USER 和 AZURE_PASSWORD。

  • 或者，可以将凭据存储在 ~/.azure/credentials 中。这是一个 ini 文件，其中包含一个 [default] 部分和以下键：subscription_id、client_id、secret 和 tenant 或 subscription_id、ad_user 和 password。也可以添加其他配置文件。通过传递 profile 或在环境中设置 AZURE_PROFILE 来指定配置文件。

另请参阅

另请参阅

使用 Azure CLI 登录

如何使用 az login 命令进行身份验证。

示例

- name: Create a simplest IoT hub
  azure_rm_iothub:
    name: Testing
    resource_group: myResourceGroup
- name: Create an IoT hub with route
  azure_rm_iothub:
    resource_group: myResourceGroup
    name: Testing
    routing_endpoints:
      - connection_string: "Endpoint=sb://qux.servicebus.windows.net/;SharedAccessKeyName=quux;SharedAccessKey=****;EntityPath=myQueue"
        name: foo
        resource_type: queue
        resource_group: myResourceGroup1
    routes:
      - name: bar
        source: device_messages
        endpoint_name: foo
        enabled: true

返回值

通用返回值记录在 此处，以下是此模块独有的字段

键

描述

cloud_to_device

复杂

云到设备消息属性。

已返回：成功

max_delivery_count

整数

IoT 中心在反馈队列中尝试传递消息的次数。

请参阅 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages。

已返回：成功

示例： 10

ttl_as_iso8601

字符串

消息在被 IoT 中心过期之前可供使用的时间段。

请参阅 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages。

已返回：成功

示例： "1:00:00"

enable_file_upload_notifications

布尔值

是否启用文件上传通知。

已返回：成功

示例： true

event_endpoints

复杂

用于传递设备消息的内置终结点。

已返回：成功

endpoint

字符串

与事件中心兼容的终结点。

已返回：成功

示例： "sb://iothub-ns-testing-1478811-9bbc4a15f0.servicebus.windows.net/"

partition_count

整数

在与事件中心兼容的终结点中，用于接收设备到云消息的分区数。

请参阅 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#device-to-cloud-messages。

已返回：成功

示例： 2

partition_ids

列表 / 元素=字符串

事件终结点的分区 ID 列表。

已返回：成功

示例： ["0", "1"]

retention_time_in_days

整数

设备到云消息的保留时间（天）。

请参阅 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#device-to-cloud-messages。

已返回：成功

示例： 1

host_name

字符串

IoT 中心的主机。

已返回：成功

示例： "testing.azure-devices.net"

id

字符串

IoT 中心的资源 ID。

已返回：成功

示例： "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/myResourceGroup/providers/Microsoft.Devices/IotHubs/Testing"

ip_filters

复杂

配置规则，用于拒绝或接受来自特定 IPv4 地址的流量。

已返回：成功

action

字符串

此规则捕获的请求的所需操作。

已返回：成功

示例： "Reject"

ip_mask

字符串

一个字符串，包含规则的 CIDR 表示法中的 IP 地址范围。

已返回：成功

示例： "40.54.7.3"

name

字符串

筛选器的名称。

已返回：成功

示例： "filter"

location

字符串

IoT 中心的位置。

已返回：成功

示例： "eastus"

name

字符串

IoT 中心的名称。

已返回：成功

示例： "Testing"

resource_group

字符串

IoT 中心的资源组。

已返回：成功

示例： "myResourceGroup."

routes

复杂

将设备到云的消息路由到面向服务的终结点。

已返回：成功

condition

布尔值

路由查询的查询表达式，该表达式针对消息应用程序属性、系统属性、消息正文、设备孪生标签和设备孪生属性运行，以确定是否与终结点匹配。

有关构建查询的详细信息，请参阅 https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-routing-query-syntax

已返回：成功

示例： true

enabled

字符串

是否启用路由。

已返回：成功

示例： "True"

endpoint_name

字符串

IoT 中心将与查询匹配的消息发送到的 routing_endpoints 中的终结点的名称。

已返回：成功

示例： "foo"

name

字符串

路由的名称。

已返回：成功

示例： "route1"

source

字符串

要对其执行操作的数据流的源。

已返回：成功

示例： "device_messages"

routing_endpoints

复杂

自定义终结点。

已返回：成功

event_hubs

复杂

事件中心的自定义终结点列表。

已返回：成功

connection_string

字符串

自定义终结点的连接字符串。

已返回：成功

示例: "Endpoint=sb://quux.servicebus.windows.net:5671/;SharedAccessKeyName=qux;SharedAccessKey=****;EntityPath=foo"

name

字符串

自定义终结点的名称。

已返回：成功

示例： "foo"

resource_group

字符串

终结点的资源组。

已返回：成功

示例: "bar"

subscription

字符串

终结点的订阅 ID。

已返回：成功

示例: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

service_bus_queues

复杂

服务总线队列的自定义端点列表。

返回: 总是

connection_string

字符串

自定义终结点的连接字符串。

已返回：成功

示例: "Endpoint=sb://quux.servicebus.windows.net:5671/;SharedAccessKeyName=qux;SharedAccessKey=****;EntityPath=foo"

name

字符串

自定义终结点的名称。

已返回：成功

示例： "foo"

resource_group

字符串

终结点的资源组。

已返回：成功

示例: "bar"

subscription

字符串

端点的订阅 ID。

已返回：成功

示例: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

service_bus_topics

复杂

服务总线主题的自定义端点列表。

已返回：成功

connection_string

字符串

自定义终结点的连接字符串。

已返回：成功

示例: "Endpoint=sb://quux.servicebus.windows.net:5671/;SharedAccessKeyName=qux;SharedAccessKey=****;EntityPath=foo"

name

字符串

自定义终结点的名称。

已返回：成功

示例： "foo"

resource_group

字符串

终结点的资源组。

已返回：成功

示例: "bar"

subscription

字符串

端点的订阅 ID。

已返回：成功

示例: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

storage_containers

复杂

存储的自定义端点列表

已返回：成功

connection_string

字符串

自定义终结点的连接字符串。

已返回：成功

示例: "Endpoint=sb://quux.servicebus.windows.net:5671/;SharedAccessKeyName=qux;SharedAccessKey=****;EntityPath=foo"

name

字符串

自定义终结点的名称。

已返回：成功

示例： "foo"

resource_group

字符串

终结点的资源组。

已返回：成功

示例: "bar"

subscription

字符串

端点的订阅 ID。

已返回：成功

示例: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

sku

字符串

Azure IoT 中心的定价层。

已返回：成功

示例: "f1"

unit

整数

IoT Hub 中的单位。

已返回：成功

示例： 1

作者

  • Yuwei Zhou (@yuwzho)