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

如何创建数据注册表

项目
09/16/2024

注意

Azure Maps 数据注册表服务停用

Azure Maps 数据注册表服务现已弃用，并将于 2025 年 9 月 30 日停用。有关详细信息，请参阅 Azure Maps 数据注册表生命周期结束公告。

通过数据注册表服务，可以使用 Azure Maps 帐户在 Azure 存储帐户中注册数据内容。数据的示例可能包括 Azure Maps 地理围栏服务中使用的地理围栏集合。另一个示例是包含绘图包 (DWG) 的 ZIP 文件，或者 Azure Maps Creator 用于创建或更新室内地图的 GeoJSON 文件。

先决条件

重要

本文使用 us.atlas.microsoft.com 地理 URL。如果帐户不是在美国创建的，则必须使用其他地理 URL。有关详细信息，请参阅访问 Creator 服务。
在本文的 URL 示例中，需要：
- 将 {Azure-Maps-Subscription-key} 替换为 Azure Maps 订阅密钥。
- 将 {udid} 替换为数据注册表的用户数据 ID。有关详细信息，请参阅用户数据 ID。

准备在 Azure Maps 中注册数据

需要创建一个包含所有必需组件的环境，然后才能在 Azure Maps 中注册数据。需要一个存储帐户，其中包含一个或多个容器，它们用来保存要注册的文件和用于身份验证的托管标识。本部分介绍如何准备 Azure 环境以在 Azure Maps 中注册数据。

创建托管标识

有两种类型的托管标识：系统分配的托管标识和用户分配的托管标识。系统分配的托管标识的生命周期与创建它们的资源相关联。而用户分配的托管标识可用于多个资源。有关详细信息，请参阅 Azure 资源的托管标识。

使用以下步骤创建托管标识，将其添加到 Azure Maps 帐户。

系统分配
用户分配

创建系统分配的托管标识：

转到 Azure 门户中的 Azure Maps 帐户。
从左侧菜单的“设置”部分选择“标识”。
将“状态”切换为“开”。

有关详细信息，请参阅 Azure 资源的托管标识。

创建容器并上传数据文件

在将文件添加到数据注册表之前，必须将它们上传到 Azure 存储帐户中的容器中。容器类似于文件系统中的目录，你的文件通过它们在 Azure 存储帐户中进行整理。

若要在 Azure 门户中创建容器，请执行以下步骤：

从 Azure 存储帐户内部，从导航窗格中的“数据存储”部分选择“容器”。
在“容器”窗格中选择“+ 容器”，打开“新建容器”窗格。
选择“创建”创建容器。

创建容器后，可以将文件上传到其中。
创建容器后，请将其选中。
从工具栏中选择“上传”，选择一个或多个文件
选择“上传”按钮。

添加数据存储

创建 Azure 存储帐户并将文件上传到一个或多个容器后，即可创建将存储帐户关联到 Azure Maps 帐户的数据存储。

重要

关联到 Azure Maps 帐户的所有存储帐户必须位于同一地理位置。有关详细信息，请参阅 Azure Maps 服务地理范围。

注意

如果还没有存储帐户，请参阅创建存储帐户。

从 Azure Maps 帐户的左侧菜单中选择“数据存储”。
选择“添加”按钮。右侧会显示“添加数据存储”屏幕。
输入所需的数据存储 ID，然后从下拉列表中选择订阅名称和存储帐户。
选择“添加” 。

新的数据存储现在显示在数据存储列表中。

将角色分配给托管标识并将其添加到数据存储

创建托管标识和数据存储后，可以将托管标识添加到数据存储，并同时为它们分配“参与者”和“存储 Blob 数据读取者”角色。虽然可直接在托管标识或存储帐户中将角色添加到托管标识，你可以轻松地进行此操作，同时直接在数据存储窗格中将它们与 Azure Maps 数据存储相关联。

注意

对于与数据存储关联的每个托管标识，都需要向其授予“参与者”和“存储 Blob 数据读取者”角色。如果没有必需的权限来向托管标识授予角色，请咨询 Azure 管理员。若要将角色分配给托管标识并将其与数据存储相关联，请执行以下操作：

从 Azure Maps 帐户的左侧菜单中选择“数据存储”。
从列表中选择一个或多个数据存储，然后选择“分配角色”。
从下拉列表中选择要关联到所选数据存储的托管标识。
在“要分配的角色”下拉列表中选择“参与者”和“存储 Blob 数据读取者”。
选择“分配”按钮。

数据注册表属性

在 Azure Maps 帐户中创建数据存储后，即可收集创建数据注册表所需的属性。

有将在 HTTP 请求正文中传递的 AzureBlob 属性，以及在 URL 中传递的用户数据 ID。

AzureBlob

AzureBlob 是一个 JSON 对象，用于定义创建数据注册表所需的属性。

属性	说明
`kind`	定义要注册的对象类型。目前，AzureBlob 是唯一受支持的类型。
`dataFormat`	位于 blobUrl 中的文件的数据格式。对于空间服务，其格式可以是 GeoJSON（已弃用 ¹）；对于转换服务，其格式可以是 ZIP（已弃用 ¹）。
`msiClientId`	用于创建数据注册表的托管标识的 ID。
`linkedResource`	在 Azure Maps 帐户中注册的数据存储的 ID。数据存储包含指向正在注册的文件的链接。
`blobUrl`	指向 AzurebBlob 的位置的 URL - 该文件已导入到容器中。

¹ Azure Maps Creator 以及数据注册表和空间服务现已弃用，并将于 2025 年 9 月 30 日停用。

以下两个部分详细介绍了如何获取要用于 msiClientId 和 blobUrl 属性的值。

msiClientId 属性

msiClientId 属性是用于创建数据注册表的托管标识的 ID。有两种类型的托管标识：系统分配的托管标识和用户分配的托管标识。系统分配的托管标识的生命周期与创建它们的资源相关联。而用户分配的托管标识可用于多个资源。有关详细信息，请参阅 Azure 资源的托管标识。

系统分配
用户分配

使用系统分配的托管标识时，无需为 msiClientId 属性提供值。当 msiClientId 为 null 时，数据注册表服务会自动使用 Azure Maps 帐户的系统分配的标识。

blobUrl 属性

blobUrl 属性是正在注册的文件的路径。可以从将值添加到的容器中获取此值。数据注册表

在 Azure 门户中选择你的存储帐户。
从左侧菜单中选择“容器”。
随即显示容器列表。选择包含要注册的文件的容器。
容器随即打开，其中显示之前上传的文件的列表。
选择所需的文件，然后复制 URL。

用户数据 ID

数据注册表的用户数据 ID (udid) 是用户定义的 GUID，必须符合以下 Regex 模式：

^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

提示

udid 是创建数据注册表时必须提供的用户定义的 GUID。如果希望肯定自己拥有全局唯一标识符 (GUID)，请考虑通过运行 GUID 生成工具来创建它，例如 Guidgen.exe 命令行程序（已随 Visual Studio 提供）。

创建数据注册表

现在你已经将具有所需文件的存储帐户通过数据存储关联到你的 Azure Maps 帐户，并收集了所有必需的属性，接下来你可以使用数据注册表 API 来注册这些文件。如果 Azure 存储帐户中有多个要注册的文件，则需要对每个文件 (udid) 运行注册请求。

注意

可以注册到 Azure Maps 数据存储的文件的最大大小为 1 GB。

创建数据注册表：

系统分配
用户分配

在 HTTP 请求正文中提供引用要添加到数据注册表的存储帐户所需的信息。信息必须采用 JSON 格式并包含以下字段：
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
注意

使用系统分配的托管标识时，如果在 HTTP 请求中为 msiClientId 属性提供值，则会收到错误。

有关 HTTP 请求正文中所需属性的详细信息，请参阅数据注册表属性。

准备好 HTTP 请求正文后，执行以下 HTTP PUT 请求：

https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

有关 udid 属性的详细信息，请参阅用户数据 ID。

从响应标头复制 Operation-Location 键的值。

在 HTTP 请求正文中提供引用要添加到数据注册表的存储帐户所需的信息。信息必须采用 JSON 格式并包含以下字段：
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "{The client ID of the managed identity}",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
注意

使用用户分配的托管标识时，如果在 HTTP 请求中不为 msiClientId 属性提供值，则会收到错误。

有关 HTTP 请求正文中所需属性的详细信息，请参阅数据注册表属性。

准备好 HTTP 请求正文后，执行以下 HTTP PUT 请求：

https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

有关 udid 属性的详细信息，请参阅用户数据 ID。

从响应标头复制 Operation-Location 键的值。

提示

如果修改了以前注册的文件的内容，其数据验证将失败，并且在重新注册之前，将无法在 Azure Maps 中使用。若要重新注册文件，请重新运行注册请求，传入用于创建原始注册的同一 AzureBlob。 Operation-Location 键的值是用于在下一部分中检查数据注册表创建状态的状态 URL，它包含 Get 操作 API 使用的操作 ID。

备注

Operation-Location 键的值不包含 subscription-key；在使用它来检查数据注册表创建状态时，需要将其添加到请求 URL 中。

检查数据注册表创建状态

若要检查数据注册表创建过程的状态（此操作可选），请输入在创建数据注册表部分复制的状态 URL，并将订阅密钥添加为查询字符串参数。请求应类似于以下 URL：

https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}

获取数据注册表中所有文件的列表

使用 List 请求获取在 Azure Maps 帐户中注册的所有文件的列表：

https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}

以下示例展示了三种可能的状态：已完成、正在运行和已失败：

{
  "value": [
    {
      "udid": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
      "description": "Contoso Indoor Design",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "zip",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path1.zip",
        "sizeInBytes": 29920,
        "contentMD5": "CsFxZ2YSfxw3cRPlqokV0w=="
      },
      "status": "Completed"
    },
    {
      "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path2.geojson",
        "sizeInBytes": 1339
      },
      "status": "Running"
    },
    {
      "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",
      "description": "Contoso Geofence GeoJSON",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path3.geojson",
        "sizeInBytes": 1650,
        "contentMD5": "rYpEfIeLbWZPyaICGEGy3A=="
      },
      "status": "Failed",
      "error": {
        "code": "ContentMD5Mismatch",
        "message": "Actual content MD5: sOJMJvFParkSxBsvvrPOMQ== doesn't match expected content MD5: CsFxZ2YSfxw3cRPlqokV0w==."
      }
    }
  ]
}

运行 List 请求时返回的数据与创建注册表时提供的数据类似，但还包括其他一些内容：

property	description
contentMD5	根据正在注册的文件的内容创建的 MD5 哈希。有关详细信息，请参阅数据验证
sizeInBytes	内容的大小（以字节为单位）。

替换数据注册表

如果需要将以前注册的文件替换为另一个文件，请重新运行注册请求，传入用于创建原始注册的同一 AzureBlob，blobUrl 除外。需要修改 BlobUrl，使其指向新文件。

数据验证

使用数据注册表 API 在 Azure Maps 中注册文件时，将根据文件的内容创建 MD5 哈希，将其编码为 128 位指纹，并将其作为 contentMD5 属性保存在 AzureBlob 中。存储在 contentMD5 属性中的 MD5 哈希用于确保文件的数据完整性。由于 MD5 哈希算法在输入相同的情况下始终生成相同的输出，因此数据验证过程可将注册文件时文件的 contentMD5 属性与 Azure 存储帐户中文件的哈希进行比较，以检查其是否完好无损且未修改。如果哈希不相同，则验证失败。如果基础存储帐户中的文件发生更改，验证会失败。如果需要修改已在 Azure Maps 中注册的文件的内容，则需要重新注册该文件。

通过