將自訂網域名稱指派給事件方格命名空間的 MQTT 和 HTTP 主機名稱

發行項
05/21/2024

事件方格命名空間會在建立時自動獲指派 HTTP 主機名稱。如果在命名空間上啟用 MQTT，也會將 MQTT 主機名稱指派給該命名空間。您的用戶端會使用這些主機名稱，與事件方格命名空間通訊。

您可以將自訂網域名稱指派給事件方格命名空間的 MQTT 和 HTTP 主機名稱，以及預設主機名稱。自訂網域設定不僅協助您符合安全性和合規性需求，也使您不需要修改已連結至網域的用戶端。

必要條件

若要針對命名空間使用自訂網域，您必須具備下列必要條件：

您擁有且可以修改其網域名稱系統 (DNS) 記錄的自訂網域。若要修改 DNS 記錄，您需要存取網域提供者 (例如 GoDaddy) 的 DNS 登錄。
自訂網域的安全通訊端層 (SSL) 憑證，來自公用或私人 CA。
Azure Key Vault 帳戶，用來裝載自訂網域的 SSL 憑證。

高階步驟

若要針對命名空間使用自訂網域，請遵循下列步驟：

新增 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 帳戶：

使用下列命令取得事件方格命名空間系統受控識別主體識別碼

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

取得 Azure Key Vault 資源識別碼。

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

在 Key Vault 中為命名空間的受控識別新增角色指派。
```
az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
```
如需 Key Vault 存取和入口網站體驗的詳細資訊，請參閱透過 Azure 角色型存取控制，提供 Key Vault 金鑰、憑證和祕密的存取權。

將事件方格命名空間與自訂網域建立關聯

在此步驟中，您會將未驗證的自訂網域與命名空間建立關聯，但直到您在下一個步驟中證明了自訂網域的擁有權，才能使用自訂網域。

使用 Azure 入口網站

請使用下列步驟來新增您的自訂網域：

在 Azure 入口網站中，瀏覽到您的事件方格命名空間
在 [事件中樞命名空間] 頁面上，選取左側導覽功能表上的 [自訂網域]。
在 [自訂網域] 頁面上，選取 [+ 自訂網域]。
在 [新增自訂網域] 頁面上，指定下列屬性的值：
1. 網域名稱：要指派給其中一個事件方格命名空間主機名稱的完整網域名稱。
2. 相關聯的主機名稱類型：要與自訂網域名稱相關聯的預設主機名稱類型。
3. 憑證 URL：Azure Key Vault 中伺服器憑證的憑證識別碼。排除憑證識別碼的最後一個區段，只包含憑證的基礎識別碼。您可以改為選擇 [使用金鑰保存庫選取憑證]，從您的訂用帳戶選取憑證和金鑰保存庫。
4. 受控識別：此受控識別用來透過 Key Vault 進行驗證，以存取已建立的伺服器憑證。
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 訂用帳戶識別碼。
`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"
                    }
                }
            ]
        }
    }
}

共用方式為