Como criar um registro de dados

O serviço de registro de dados permite que você registre conteúdo de dados em uma Conta de Armazenamento do Azure com a conta do Azure Mapas. Um exemplo de dados pode incluir uma coleção de delimitações geográficas usados no serviço de Delimitação Geográfica do Azure Mapas. Outro exemplo são arquivos ZIP que contêm pacotes de desenho (DWG) ou arquivos GeoJSON que o Criador do Azure Mapas usa para criar ou atualizar Indoor Maps.

Pré-requisitos

• Uma Conta do Azure Mapas
• Uma Chave de assinatura
• Uma conta do Armazenamento do Azure

Preparar-se para registrar dados no Azure Mapas

Para registrar dados no Azure Mapas, você precisa criar um ambiente que contenha todos os componentes necessários. Você precisa de uma conta de armazenamento com um ou mais contêineres que retenham os arquivos que deseja registrar e identidades gerenciadas para autenticação. Esta seção explica como preparar o ambiente do Azure para registrar dados no Azure Mapas.

Criar identidades gerenciadas

Há dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. As identidades gerenciadas atribuídas pelo sistema têm seu ciclo de vida associado ao recurso que as criou. As identidades gerenciadas atribuídas pelo usuário podem ser usadas em vários recursos. Para saber mais, confira identidades gerenciadas para recursos do Azure.

Execute as etapas a seguir para criar uma identidade gerenciada e adicioná-la à conta do Azure Mapas.

Para saber mais, confira identidades gerenciadas para recursos do Azure.

Criar um contêiner e carregar arquivos de dados

Antes de adicionar arquivos a um registro de dados, você precisa carregá-los em um contêiner na conta de armazenamento do Azure. Os contêineres são semelhantes a um diretório em um sistema de arquivos. Eles são a maneira de organizar os arquivos na conta de armazenamento do Azure.

Para criar um contêiner no portal do Azure, siga estas etapas:

1. Na conta de armazenamento do Azure, selecione Contêineres na seção Armazenamento de dados no painel de navegação.

2. Selecione + Contêiner no painel Contêineres para abrir o painel Novo contêiner.

3. Selecione Criar para criar o contêiner.

   

   Depois que o contêiner for criado, você poderá carregar arquivos nele.

4. Depois que o contêiner for criado, selecione-o.

   

5. Selecione Carregar na barra de ferramentas e escolha um ou mais arquivos

6. Selecione o botão Carregar.

   

Adicionar um armazenamento de dados

Depois de criar uma conta de armazenamento do Azure com arquivos carregados em um ou mais contêineres, você estará pronto para criar o armazenamento de dados que vincula as contas de armazenamento à conta do Azure Mapas.

1. Selecione Armazenamento de dados no menu à esquerda na conta do Azure Mapas.

2. Selecione o botão Adicionar. Uma tela Adicionar armazenamento de dados é exibida no lado direito.

3. Insira a ID do armazenamento de dados desejada e selecione o Nome da assinatura e a Conta de armazenamento nas listas suspensas.

4. Selecione Adicionar.

   

O novo armazenamento de dados agora aparece na lista de armazenamentos de dados.

Atribuir funções a identidades gerenciadas e adicioná-las ao armazenamento de dados

Depois que as identidades gerenciadas e o armazenamento de dados forem criados, você poderá adicionar as identidades gerenciadas ao armazenamento de dados e, simultaneamente, atribuir as funções Colaborador e Leitor de Dados do Blob de Armazenamento. Embora seja possível adicionar funções às identidades gerenciadas diretamente nas identidades gerenciadas ou na conta de armazenamento, você pode fazer isso facilmente associando-as simultaneamente ao armazenamento de dados do Azure Mapas diretamente no painel do armazenamento de dados.

1. Selecione Armazenamento de dados no menu à esquerda na conta do Azure Mapas.

2. Selecione um ou mais armazenamentos de dados na lista e clique em Atribuir funções.

3. Selecione a Identidade gerenciada a ser associada aos armazenamentos de dados selecionados na lista suspensa.

4. Selecione Colaborador e Leitor de Dados do Blob de Armazenamento na lista suspensa Funções a serem atribuídas.

   

5. Selecione o botão Atribuir.

Propriedades do registro de dados

Com um armazenamento de dados criado na conta do Azure Mapas, está tudo pronto para coletar as propriedades necessárias e criar o registro de dados.

Existem as propriedades AzureBlob que você passa no corpo da solicitação HTTP e a ID de dados do usuário passada na URL.

O AzureBlob

O AzureBlob é um objeto JSON que define as propriedades necessárias para criar o registro de dados.

¹ Criador do Azure Mapas e o Registro de Dados e os serviços espaciais foram preteridos e serão desativados em 30/09/25.

As duas seções a seguir mostram detalhes de como obter os valores a serem usados para as propriedades msiClientId e blobUrl.

A propriedade msiClientId

A propriedade msiClientId é a ID da identidade gerenciada usada para criar o registro de dados. Há dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. As identidades gerenciadas atribuídas pelo sistema têm seu ciclo de vida associado ao recurso que as criou. As identidades gerenciadas atribuídas pelo usuário podem ser usadas em vários recursos. Para saber mais, confira identidades gerenciadas para recursos do Azure.

A propriedade blobUrl

A propriedade blobUrl é o caminho para o arquivo que está sendo registrado. Você pode obter esse valor do contêiner ao qual ele foi adicionado. registro de dados

1. Selecione a conta de armazenamento no portal do Azure.

2. Selecione Contêineres no menu à esquerda.

3. Uma lista de contêineres é exibida. Selecione o contêiner que contém o arquivo que você deseja registrar.

4. O contêiner é aberto, mostrando uma lista dos arquivos que já foram carregados.

5. Selecione o arquivo desejado e copie a URL.

   

A ID de dados do usuário

A ID de dados do usuário (udid) do registro de dados é um GUID definido pelo usuário que precisa estar em conformidade com o seguinte padrão 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}$

Criar um registro de dados

Agora que você já tem a conta de armazenamento com os arquivos desejados vinculados à conta do Azure Mapas por meio do armazenamento de dados e reuniu todas as propriedades necessárias, use a API de registro de dados para registrar esses arquivos. Se você tiver vários arquivos na conta de armazenamento do Azure que deseja registrar, execute a solicitação de registro para cada arquivo (udid).

Para criar um registro de dados:

Verificar o status de criação do registro de dados

Para (opcionalmente) verificar o status do processo de criação do registro de dados, insira a URL de status copiada na seção Criar um registro de dados e adicione a chave de assinatura como um parâmetro de cadeia de caracteres de consulta. A solicitação será como a seguinte URL:

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

Obter uma lista de todos os arquivos no registro de dados

Usando a solicitação List para obter uma lista de todos os arquivos registrados em uma conta do Azure Mapas:

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

O exemplo a seguir demonstra três status possíveis (concluídos, em execução e com falha):

{
  "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==."
      }
    }
  ]
}

Os dados retornados ao executar a solicitação de listagem são semelhantes aos dados fornecidos ao criar um registro, com algumas adições:

Substituir um registro de dados

Se você precisar substituir um arquivo já registrado por outro arquivo, execute novamente a solicitação de registro, passando o mesmo AzureBlob usado para criar o registro original, exceto a blobUrl. O BlobUrl precisa ser modificado a fim de apontar para o novo arquivo.

Validação de dados

Quando você registra um arquivo no Azure Mapas usando a API de registro de dados, um hash MD5 é criado com base no conteúdo do arquivo, codificando-o em uma impressão digital de 128 bits e salvando-o no AzureBlob no como a propriedade contentMD5. O hash MD5 armazenado na propriedade contentMD5 é usado para garantir a integridade dos dados do arquivo. Como o algoritmo de hash MD5 sempre produz a mesma saída quando usa a mesma entrada, o processo de validação de dados pode comparar a propriedade contentMD5 do arquivo quando ele foi registrado em relação a um hash do arquivo na conta de armazenamento do Azure para verificar se ele está intacto e sem modificação. Se o hash não for o mesmo, a validação falhará. Se o arquivo na conta de armazenamento subjacente for alterado, a validação falha. Se você precisar modificar o conteúdo de um arquivo que foi registrado no Azure Mapas, será necessário registrá-lo novamente.