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

如何创建数据注册表

注意

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 帐户。

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

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

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

创建容器并上传数据文件

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

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

  1. 从 Azure 存储帐户内部,从导航窗格中的“数据存储”部分选择“容器”。

  2. 在“容器”窗格中选择“+ 容器”,打开“新建容器”窗格。

  3. 选择“创建”创建容器。

    Azure 存储帐户中的“新建容器”页的屏幕截图。

    创建容器后,可以将文件上传到其中。

  4. 创建容器后,请将其选中。

    显示刚刚在 Azure 存储帐户中创建的新容器的屏幕截图。

  5. 从工具栏中选择“上传”,选择一个或多个文件

  6. 选择“上传”按钮。

    创建容器时显示的“上传 Blob”页的屏幕截图。

添加数据存储

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

重要

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

注意

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

  1. 从 Azure Maps 帐户的左侧菜单中选择“数据存储”。

  2. 选择“添加”按钮。 右侧会显示“添加数据存储”屏幕。

  3. 输入所需的数据存储 ID,然后从下拉列表中选择订阅名称和存储帐户。

  4. 选择“添加” 。

    显示“添加数据存储”屏幕的屏幕截图。

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

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

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

注意

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

  1. 从 Azure Maps 帐户的左侧菜单中选择“数据存储”。

  2. 从列表中选择一个或多个数据存储,然后选择“分配角色”。

  3. 从下拉列表中选择要关联到所选数据存储的托管标识。

  4. 在“要分配的角色”下拉列表中选择“参与者”和“存储 Blob 数据读取者”。

    显示“将角色分配到数据存储”屏幕的屏幕截图。

  5. 选择“分配”按钮。

数据注册表属性

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

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

AzureBlob

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

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

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

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

msiClientId 属性

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

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

blobUrl 属性

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

  1. 在 Azure 门户中选择你的存储帐户。

  2. 从左侧菜单中选择“容器”。

  3. 随即显示容器列表。 选择包含要注册的文件的容器。

  4. 容器随即打开,其中显示之前上传的文件的列表。

  5. 选择所需的文件,然后复制 URL。

    显示如何选择用作 blobUrl 属性的 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。

创建数据注册表:

  1. 在 HTTP 请求正文中提供引用要添加到数据注册表的存储帐户所需的信息。 信息必须采用 JSON 格式并包含以下字段:

    {
    "kind": "AzureBlob",
        "azureBlob": {
            "dataFormat": "geojson",
            "linkedResource": "{datastore ID}",
            "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
        }
    }
    

    注意

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

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

  2. 准备好 HTTP 请求正文后,执行以下 HTTP PUT 请求:

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

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

  3. 从响应标头复制 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 内容的大小(以字节为单位)。

替换数据注册表

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

数据验证

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