你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将自定义域名分配给事件网格命名空间的 MQTT 和 HTTP 主机名

项目
05/21/2024

事件网格命名空间在创建时会自动分配有一个 HTTP 主机名。如果在命名空间上启用了 MQTT，则还会为命名空间分配 MQTT 主机名。客户端使用这些主机名与事件网格命名空间进行通信。

可以将自定义域名以及默认主机名分配给事件网格命名空间的 MQTT 和 HTTP 主机名。自定义域配置不仅有助于满足安全性和合规性要求，还消除了修改已链接到域的客户端的需要。

先决条件

若要对命名空间使用自定义域，需要满足以下先决条件：

你拥有的且可以修改其域名系统 (DNS) 记录的自定义域。要修改 DNS 记录，需要有权访问域提供商（例如 GoDaddy）的 DNS 注册表。
来自公共或专用 CA 的自定义域的安全套接字层 (SSL) 证书。
用于托管自定义域的 SSL 证书的 Azure Key Vault 帐户。

简要步骤

若要将自定义域用于命名空间，请执行以下步骤：

添加 DNS 条目以将自定义域指向事件网格命名空间终结点。
为事件网格命名空间启用托管标识。
创建托管自定义域服务器证书的 Azure Key Vault 帐户。
在 Azure Key Vault 中为命名空间的托管标识添加角色分配。
将事件网格命名空间与自定义域相关联，并指定自定义域名、证书名称和密钥保管库实例引用。
事件网格命名空间生成一条 TXT 记录，用于证明自定义域的所有权。
根据上一步中生成的事件网格值创建 TXT 记录，来证明域所有权。
在激活自定义域供客户端使用之前，事件网格会验证自定义域的 TXT 记录。
客户端可以通过自定义域连接到事件网格命名空间。

限制

在每个区域中，MQTT 和 HTTP 主机名的自定义域配置是唯一的。
同一命名空间下的 MQTT 和 HTTP 主机名的自定义域配置不能相同。
自定义域配置不能与同一区域中任何命名空间的任何 MQTT 或 HTTP 主机名冲突。

添加 DNS 条目

在域中创建 DNS 记录，以指向要与域关联的事件网格命名空间的主机名。若要了解详细信息，请查看为 Azure 云服务配置自定义域名。

命名空间的 HTTP 主机名采用以下格式：<namespace name>.centraluseuap-1.eventgrid.azure.net

命名空间的 MQTT 主机名采用以下格式：<namespace name>.centraluseuap-1.ts.eventgrid.azure.net

在事件网格命名空间上启用托管标识

命名空间使用托管标识访问 Azure Key Vault 实例，以获取自定义域的服务器证书。使用以下命令在事件网格命名空间上启用系统分配的托管标识：

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

有关使用 Azure 门户配置系统和用户分配的标识的信息，请参阅为事件网格命名空间启用托管标识。

创建 Azure Key Vault 帐户并上传服务器证书

使用以下命令创建 Azure Key Vault 帐户：

az keyvault create --name "<your-unique-keyvault-name>" --resource-group "<resource group name>" --location "centraluseaup"

使用以下命令将证书导入 Azure Key Vault
```
az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
```
注意

证书必须在 DNS 的使用者可选名称中包含域名。有关详细信息，请参阅教程：在 Azure Key Vault 中导入证书。

在 Azure Key Vault 中为命名空间的托管标识添加角色分配

需要使用以下步骤提供对命名空间的访问权限才能访问 Azure Key Vault 帐户：

使用以下命令获取事件网格命名空间系统托管标识主体 ID

$principalId=(az eventgrid namespace show --resource-group <resource group name> --name <namespace name> --query identity.principalId -o tsv)

获取 Azure 密钥保管库资源 ID。

$keyVaultResourceId=(az keyvault show --resource-group <resource group name> --name <your key vault name> --query id -o tsv)

在密钥保管库中为命名空间的托管标识添加角色分配。
```
az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
```
有关密钥保管库访问和门户体验的详细信息，请参阅使用 Azure 基于角色的访问控制提供对密钥保管库密钥、证书和机密的访问权限。

将事件网格命名空间与自定义域相关联

在此步骤中，将未验证的自定义域与命名空间相关联，但在下一步中证明自定义域的所有权之前，不能使用它。

使用 Azure 门户

使用以下步骤添加自定义域：

在 Azure 门户中，导航到事件网格命名空间
在“事件网格命名空间”页中，在左侧导航菜单上选择“自定义域”。
在“自定义域”页中，选择“添加自定义域”。
在“添加自定义域”页上，指定以下属性的值：
1. 域名：要分配给某个事件网格命名空间主机名的完全限定的域名。
2. 关联的主机名类型：要与自定义域名关联的默认主机名类型。
3. 证书 URL：Azure Key Vault 中服务器证书的证书标识符。仅包含证书的基标识符，不包括证书标识符的最后一段。可以改为选择“使用密钥保管库选择证书”，从订阅中选择证书和密钥保管库。
4. 托管标识：用于向密钥保管库进行身份验证以访问创建的服务器证书的托管标识。
5. 选择“添加”
保存 TXT 记录，因为需要使用这些值来证明自定义域所有权。

Azure CLI 示例

使用以下命令通过自定义域配置更新命名空间。以下对象包括两种不同的 customDomains 配置：topicSpacesConfiguration 下的配置将分配给 MQTT 终结点，topicsConfiguration 下的配置将分配给 HTTP 终结点。

注意

每个自定义域配置在同一区域中必须是唯一的。

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --properties @./resources/NS.json

NS.json

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/NAMESPACENAME/topics/TOPICNAME",
            "hostname": "NAMESPACENAME.westus2-1.ts.eventgrid.azure.net",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": " www.MQTTDOMAINNAME.com ",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/SUBSCRIPTIONNAME/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        }
    }
}

将以下占位符替换为适当的值，将其保存到名为 NS.json 的文件，并运行 CLI 命令。

占位符	说明
`HOSTNAME`	可以从 Azure 门户中事件网格命名空间的“概述”页获取主机名。
`NAMESPACENAME`	事件网格命名空间的名称。
`TOPICNAME`	命名空间中主题的名称。
`HTTPDOMAINNAME`	HTTP 域的名称。
`MQTTDOMAINNAME`	MQTT 域的名称。
`SUBSCRIPTIONID`	Azure 订阅 ID。
`RESOURCEGROUPNAME`	Azure 资源组的名称。
`KEYVAULTNAME`	密钥保管库的名称。
`CERTIFICATENAME`	证书的名称。

标识类型 (type) 可以是 SystemAssigned 或 UserAssigned。如果选择 UserAssigned，请使用 userAssignedIdentity 属性指定用户分配的标识。

对此操作的响应包括以下属性形式的 DNS 信息：expectedTxtRecordName 和 expectedTxtRecordValue。保存此信息，因为需要使用这些值来证明自定义域所有权。示例响应如下：

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "validationState": "Pending",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    },
                    "expectedTxtRecordName": "_eg. www.contoso-http.com",
                    "expectedTxtRecordValue": "<random string>"
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/MSNS/topics/TOPICNAME",
            "hostname": "HOSTNAME",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": " www.MQTTDOMAINNAME.com ",
                    "validationState": "Pending",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    },
                    "expectedTxtRecordName": "_eg. www.contoso-mqtt.com",
                    "expectedTxtRecordValue": "<random string>"
                }
            ]
        }
    }
}

证明自定义域所有权

若要证明域所有权，请执行以下步骤：

添加 DNS 信息。

返回到域注册机构，根据从上一步复制的 DNS 信息为域创建新的 TXT 记录。为域创建此 TXT 可以验证域名的所有权。将生存时间 (TTL) 设置为 3,600 秒（60 分钟），然后保存记录。

验证自定义域名。

若要使用 Azure 门户，请执行以下步骤来验证自定义域：
1. 在“自定义域”页上，选择“验证域”。
2. 在“验证域”页上，选择“验证”。

使用以下命令通过相同的自定义域配置更新命名空间。此命令将触发自定义域所有权的验证。 DNS 记录必须传播，然后你才能验证域，DNS 设置的传播时间取决于域注册机构。

在对命令的响应中，验证 validationState 是否为 Approved。

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --properties @./resources/NS.json

NS.json：

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/AZURESUBCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/AZURESUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/NAMESPACENAME/topics/TOPICNAME",
            "hostname": "HOSTNAME",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.MQTTDOMAINNAME.com ",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/AZURESUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        }
    }
}

通过