Создание реестра данных

Статья
06/14/2023

Служба реестра данных позволяет регистрировать содержимое данных в учетной записи хранения Azure с помощью учетной записи Azure Maps. Примером данных может быть коллекция геозон, используемых в службе геозон Azure Maps. Другим примером являются ZIP-файлы, содержащие пакеты рисования (DWG) или файлы GeoJSON, которые Azure Maps Creator использует для создания или обновления карт помещений.

Предварительные требования

Важно!

В этой статье используется географический URL-адрес us.atlas.microsoft.com. Если ваша учетная запись не была создана в США, необходимо использовать другой географический URL-адрес. Дополнительные сведения см. в разделе Доступ к службам Creator.
В примерах URL-адресов в этой статье необходимо изменить:
- {Azure-Maps-Subscription-key}с ключом подписки Azure Maps.
- {udid} с идентификатором пользовательских данных реестра данных. Дополнительные сведения см. в разделе Идентификатор данных пользователя.

Подготовка к регистрации данных в Azure Maps

Перед регистрацией данных в Azure Maps необходимо создать среду, содержащую все необходимые компоненты. Вам потребуется учетная запись хранения с одним или несколькими контейнерами, которые содержат файлы, которые вы хотите зарегистрировать, и управляемые удостоверения для проверки подлинности. В этом разделе объясняется, как подготовить среду Azure для регистрации данных в Azure Maps.

Создание управляемых удостоверений

Существует два типа управляемых удостоверений: назначаемые системой и назначаемые пользователем. Жизненный цикл управляемых удостоверений, назначаемых системой, связан с ресурсом, который их создал. Назначаемые пользователем управляемые удостоверения могут использоваться для нескольких ресурсов. Дополнительные сведения см. в статье Управляемые удостоверения для ресурсов Azure.

Выполните следующие действия, чтобы создать управляемое удостоверение и добавить его в учетную запись Azure Maps.

Назначаемое системой
Назначаемые пользователем

Создайте управляемое удостоверение, назначаемое системой:

Перейдите к своей учетной записи Azure Maps в портал Azure.
Выберите Удостоверение в меню слева.
Переведите переключатель Состояние в положение Вкл.

Дополнительные сведения см. в статье Управляемые удостоверения для ресурсов Azure.

Создание контейнера и отправка файлов данных

Перед добавлением файлов в реестр данных необходимо передать их в контейнер в учетной записи хранения Azure. Контейнеры похожи на каталог в файловой системе, так как упорядочены файлы в вашей учетной записи хранения Azure.

Чтобы создать контейнер на портале Azure, сделайте следующее:

В учетной записи хранения Azure выберите Контейнеры в разделе Хранилище данных в области навигации.
Выберите + Контейнер в области Контейнеры , чтобы открыть панель Новый контейнер .
Щелкните Создать, чтобы создать контейнер.

После создания контейнера вы можете отправить в него файлы.
После создания контейнера выберите его.
Выберите Отправить на панели инструментов и выберите один или несколько файлов.
Нажмите кнопку Отправить.

Добавление хранилища данных

После создания учетной записи хранения Azure с файлами, отправленными в один или несколько контейнеров, вы можете создать хранилище данных, которое связывает учетные записи хранения с вашей учетной записью Azure Maps.

Важно!

Все учетные записи хранения, связанные с учетной записью Azure Maps, должны находиться в одном географическом расположении. Дополнительные сведения см. в разделе Azure Maps географических область службы.

Примечание

Если у вас нет учетной записи хранения, см. статью Создание учетной записи хранения.

Выберите Хранилище данных в меню слева в учетной записи Azure Maps.
Нажмите кнопку Добавить. Справа появится экран Добавление хранилища данных .
Введите нужный идентификатор хранилища данных , а затем выберите имя подписки и учетную запись хранения в раскрывающихся списках.
Выберите Добавить.

Новое хранилище данных теперь отображается в списке хранилищ данных.

Назначение ролей управляемым удостоверениям и их добавление в хранилище данных

После создания управляемых удостоверений и хранилища данных можно добавить управляемые удостоверения в хранилище данных и одновременно назначить им роли Участник и Читатель данных BLOB-объектов хранилища . Хотя можно добавить роли в управляемые удостоверения непосредственно в управляемые удостоверения или учетную запись хранения, что можно легко сделать, одновременно связав их с хранилищем данных Azure Maps непосредственно в области хранилища данных.

Примечание

Каждому управляемому удостоверению, связанному с хранилищем данных, потребуются роли участника и читателя данных BLOB-объектов хранилища . Если у вас нет необходимых разрешений для предоставления ролей управляемым удостоверениям, обратитесь к администратору Azure. Чтобы назначить роли управляемым удостоверениям и связать их с хранилищем данных, выполните приведенные ниже действия.

Выберите Хранилище данных в меню слева в учетной записи Azure Maps.
Выберите одно или несколько хранилищ данных из списка, а затем — Назначить роли.
Выберите управляемое удостоверение , чтобы связать его с выбранными хранилищами данных из раскрывающегося списка.
Выберите Участник и Читатель данных BLOB-объектов хранилища в раскрывающемся списке Роли для назначения .
Нажмите кнопку Назначить.

Свойства реестра данных

С помощью хранилища данных, созданного в учетной записи Azure Maps, вы можете собрать свойства, необходимые для создания реестра данных.

В тексте HTTP-запроса передаются свойства AzureBlob, а в URL-адресе передается идентификатор данных пользователя .

The AzureBlob

— AzureBlob это объект JSON, который определяет свойства, необходимые для создания реестра данных.

Свойство	Описание
`kind`	Определяет тип регистрируемого объекта. В настоящее время поддерживается только AzureBlob .
`dataFormat`	Формат данных файла, расположенного в blobUrl. Его формат может быть GeoJSON для пространственной службы или ZIP для службы преобразования.
`msiClientId`	Идентификатор управляемого удостоверения, используемого для создания реестра данных.
`linkedResource`	Идентификатор хранилища данных, зарегистрированного в учетной записи Azure Maps. Хранилище данных содержит ссылку на регистримый файл.
`blobUrl`	URL-адрес, указывающий на расположение AzurebBlob, файла, импортированного в контейнер.

В следующих двух разделах содержатся сведения о том, как получить значения, используемые для свойств msiClientId, blobUrl .

Свойство msiClientId

Свойство msiClientId — это идентификатор управляемого удостоверения, используемого для создания реестра данных. Существует два типа управляемых удостоверений: назначаемые системой и назначаемые пользователем. Жизненный цикл управляемых удостоверений, назначаемых системой, связан с ресурсом, который их создал. Назначаемые пользователем управляемые удостоверения могут использоваться для нескольких ресурсов. Дополнительные сведения см. в статье Управляемые удостоверения для ресурсов Azure.

Назначаемое системой
назначаемые пользователем

При использовании управляемых удостоверений, назначаемых системой, не нужно предоставлять значение для msiClientId свойства . Служба реестра данных автоматически использует назначенное системой удостоверение учетной записи Azure Maps, если msiClientId имеет значение NULL.

Значение, используемое msiClientId для свойства, является идентификатором клиента управляемого удостоверения, назначаемого пользователем.

В учетной записи Azure Maps выберите Удостоверение в меню слева.
Наведите указатель мыши на имя управляемого идентификатора, пока оно не появится в виде ссылки, а затем выберите его.
Скопируйте идентификатор клиента.

Свойство blobUrl

Свойство blobUrl — это путь к регистрируемого файлу. Это значение можно получить из контейнера, в который оно было добавлено. реестр данных

Выберите учетную запись хранения в портал Azure.
В меню слева выберите Контейнеры .
Появится список контейнеров. Выберите контейнер, содержащий файл, который требуется зарегистрировать.
Откроется контейнер со списком ранее отправленных файлов.
Выберите нужный файл и скопируйте URL-адрес.

Идентификатор данных пользователя

Идентификатор данных пользователя (udid) реестра данных — это определяемый пользователем GUID, который должен соответствовать следующему шаблону регулярного выражения:

^[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 хранилище данных, составляет один гигабайт.

Чтобы создать реестр данных, выполните следующие действия.

Назначаемое системой
назначаемые пользователем

Укажите сведения, необходимые для ссылки на учетную запись хранения, добавляемую в реестр данных, в тексте HTTP-запроса. Сведения должны быть в формате JSON и содержать следующие поля:
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
Примечание

При использовании управляемых удостоверений, назначаемых системой, вы получите сообщение об ошибке, если указать значение свойства msiClientId в HTTP-запросе.

Дополнительные сведения о свойствах, необходимых в тексте HTTP-запроса, см. в разделе Свойства реестра данных.
Когда текст HTTP-запроса будет готов, выполните следующий HTTP-запрос PUT:
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
Дополнительные сведения о свойстве см. в udid разделе Идентификатор данных пользователя.
Скопируйте значение ключа 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"
    }
}
```
Примечание

При использовании управляемых удостоверений, назначаемых пользователем, вы получите сообщение об ошибке, если не указать значение свойства msiClientId в HTTP-запросе.

Дополнительные сведения о свойствах, необходимых в тексте HTTP-запроса, см. в разделе Свойства реестра данных.
Когда текст HTTP-запроса будет готов, выполните следующий HTTP-запрос PUT:
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
Дополнительные сведения о свойстве см. в udid разделе Идентификатор данных пользователя.
Скопируйте значение ключа Operation-Location из заголовка ответа.

Совет

Если содержимое ранее зарегистрированного файла будет изменено, проверка данных завершится ошибкой и не будет использоваться в Azure Maps до повторной регистрации. Чтобы повторно зарегистрировать файл, повторно запустите запрос на регистрацию, передав тот же объект AzureBlob , который использовался для создания исходной регистрации. Значение ключа Operation-Location — это URL-адрес состояния, который будет использоваться для проверка состояния создания реестра данных в следующем разделе. Он содержит идентификатор операции, используемый API операции Get.

Примечание

Значение раздела Operation-Location не будет содержать subscription-key, необходимо добавить его в 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==."
      }
    }
  ]
}

Данные, возвращаемые при выполнении запроса списка, аналогичны данным, предоставленным при создании реестра с несколькими дополнениями:

свойство;	description
contentMD5	Хэш MD5, созданный на основе содержимого регистрируемого файла. Дополнительные сведения см. в разделе Проверка данных.
sizeInBytes	Размер содержимого в байтах.

Замена реестра данных

Если необходимо заменить ранее зарегистрированный файл другим файлом, повторно выполните запрос на регистрацию, передав тот же объект AzureBlob , который использовался для создания исходной регистрации, за исключением blobUrl. Необходимо BlobUrl изменить так, чтобы он указывал на новый файл.

Проверка данных

При регистрации файла в Azure Maps с помощью API реестра данных из содержимого файла создается хэш MD5, кодирующий его в 128-разрядный отпечаток и сохраняющий его в AzureBlob качестве contentMD5 свойства . Хэш MD5, хранящийся в свойстве contentMD5 , используется для обеспечения целостности данных файла. Так как хэш-алгоритм MD5 всегда создает одни и те же выходные данные при одинаковых входных данных, процесс проверки данных может сравнить contentMD5 свойство файла при его регистрации с хэшом файла в учетной записи хранения Azure, чтобы проверка, что он нетронут и неизменен. Если хэш не совпадает, проверка завершается ошибкой. Если файл в базовой учетной записи хранения изменяется, проверка завершается ошибкой. Если необходимо изменить содержимое файла, зарегистрированного в Azure Maps, его необходимо зарегистрировать еще раз.

Создание реестра данных

Предварительные требования

Подготовка к регистрации данных в Azure Maps

Создание управляемых удостоверений

Создание контейнера и отправка файлов данных

Добавление хранилища данных

Назначение ролей управляемым удостоверениям и их добавление в хранилище данных

Свойства реестра данных

The AzureBlob

Свойство msiClientId

Свойство blobUrl

Идентификатор данных пользователя

Создание реестра данных

Проверка состояния создания реестра данных

Получение списка всех файлов в реестре данных

Замена реестра данных

Проверка данных

Дополнительные ресурсы