Como criar registo de dados

Nota

Desativação do serviço de registo de Dados do Azure Maps

O serviço de registo de Dados do Azure Maps foi agora preterido e será descontinuado em 30/09/25. Para obter mais informações, consulte Anúncio de fim da vida útil do Registro de Dados do Azure Maps.

O serviço de registo de dados permite-lhe registar conteúdo de dados numa Conta de Armazenamento do Azure com a sua conta do Azure Maps. Um exemplo de dados pode incluir uma coleção de Geofences usadas no serviço de Geofencing do Azure Maps. Outro exemplo são arquivos ZIP contendo pacotes de desenho (DWG) ou arquivos GeoJSON que o Azure Maps Creator usa para criar ou atualizar mapas internos.

Pré-requisitos

• Uma conta do Azure Maps
• Uma chave de subscrição
• Uma Conta do Storage do Azure

Importante

• Este artigo usa o us.atlas.microsoft.com URL geográfico. Se a sua conta não tiver sido criada nos Estados Unidos, tem de utilizar um URL geográfico diferente. Para obter mais informações, consulte Acesso aos serviços do Criador.
• Nos exemplos de URL neste artigo, você precisará substituir:
  • {Azure-Maps-Subscription-key}com a sua chave de subscrição do Azure Maps.
  • {udid} com o ID de dados do utilizador do seu registo de dados. Para obter mais informações, consulte A ID de dados do usuário.

Preparar para registrar dados no Azure Maps

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

Criar identidades gerenciadas

Existem dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. As identidades gerenciadas atribuídas ao sistema têm seu ciclo de vida vinculado ao recurso que as criou. As identidades gerenciadas atribuídas pelo usuário podem ser usadas em vários recursos. Para obter mais informações, consulte identidades gerenciadas para recursos do Azure.

Use as etapas a seguir para criar uma identidade gerenciada, adicione-a à sua conta do Azure Maps.

atribuído pelo sistema

Crie uma identidade gerenciada atribuída ao sistema:

1. Aceda à sua conta do Azure Maps no portal do Azure.
2. Selecione Identidade na seção Configurações no menu à esquerda.
3. Alterne o status para Ativado.

atribuído pelo usuário

Crie uma identidade gerenciada atribuída ao usuário:

1. Vá para o portal do Azure e selecione Criar um recurso.

2. No controle Serviços de pesquisa e marketplace, insira a identidade gerenciada atribuída ao usuário.

3. Na página Criar Identidade Gerenciada Atribuída ao Usuário, selecione sua assinatura, grupo de recursos, região e um nome para sua identidade gerenciada.

4. Selecione Rever + criar e, uma vez pronto, Criar.

   

5. Na sua conta do Azure Maps, selecione Identidade na seção Configurações do menu à esquerda.

6. Selecione a guia Usuário atribuído .

7. Selecione + Adicionar.

8. Na tela Adicionar identidade gerenciada atribuída ao usuário, selecione a Assinatura desejada e a identidade gerenciada.

9. Selecione Adicionar

   

A identidade gerenciada definida pelo usuário agora deve ser adicionada à sua conta do Azure Maps.

Para obter mais informações, consulte 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ê deve carregá-los em um contêiner em sua conta de armazenamento do Azure. Os contêineres são semelhantes a um diretório em um sistema de arquivos, eles são como seus arquivos são organizados em sua conta de armazenamento do Azure.

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

1. Na sua 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 exibir o painel Novo contêiner .

3. Selecione Criar para criar o contentor.

   

   Uma vez que seu contêiner tenha sido criado, você pode carregar arquivos nele.

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

   

5. Selecione Carregar na barra de ferramentas, selecione 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 à sua conta do Azure Maps.

Importante

Todas as contas de armazenamento vinculadas a uma conta do Azure Maps devem estar no mesmo local geográfico. Para obter mais informações, consulte Escopo geográfico do serviço Azure Maps.

Nota

Se você não tiver uma conta de armazenamento, consulte Criar uma conta de armazenamento.

1. Selecione Datastore no menu esquerdo da sua conta do Azure Maps.

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

3. Insira o ID do Datastore desejado 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 suas identidades gerenciadas e o armazenamento de dados forem criados, você poderá adicionar as identidades gerenciadas ao armazenamento de dados e, simultaneamente, atribuir-lhes as funções de Colaborador e Leitor de Dados de Blob de Armazenamento . Embora seja possível adicionar funções às suas identidades gerenciadas diretamente em suas identidades gerenciadas ou conta de armazenamento, o que você pode fazer facilmente ao associá-las simultaneamente ao seu armazenamento de dados do Azure Maps diretamente no painel de armazenamento de dados.

Nota

Cada identidade gerenciada associada ao armazenamento de dados precisará das funções de Colaborador e Leitor de Dados de Blob de Armazenamento concedidas a eles. Se você não tiver as permissões necessárias para conceder funções a identidades gerenciadas, consulte o administrador do Azure. Para atribuir funções às suas identidades gerenciadas e associá-las a um armazenamento de dados:

1. Selecione Datastore no menu esquerdo da sua conta do Azure Maps.

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

3. Selecione a identidade gerenciada a ser associada ao(s) armazenamento(s) de dados selecionado(s) na lista suspensa.

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

   

5. Selecione o botão Atribuir .

Propriedades do registo de dados

Com um armazenamento de dados criado em sua conta do Azure Maps, você está pronto para reunir as propriedades necessárias para criar o registro de dados.

Há 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.

Property	Description
kind	Define o tipo de objeto que está sendo registrado. Atualmente , AzureBlob é o único tipo suportado.
dataFormat	O formato de dados do arquivo localizado em blobUrl. Seu formato pode ser GeoJSON para o serviço espacial (Deprecated1) ou ZIP para o serviço de conversão (Deprecated1).
msiClientId	A ID da identidade gerenciada que está sendo usada para criar o registro de dados.
linkedResource	A ID do armazenamento de dados registrado na conta do Azure Maps. O armazenamento de dados contém um link para o arquivo que está sendo registrado.
blobUrl	Uma URL apontando para o Local do AzurebBlob, o arquivo importado para seu contêiner.

1 O Azure Maps Creator e o Registo de dados e os serviços espaciais foram agora preteridos e serão descontinuados em 30/09/25.

As duas seções a seguir fornecem detalhes sobre como obter os valores a serem usados para as propriedades msiClientId, blobUrl .

A propriedade msiClientId

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

atribuído pelo sistema

Ao usar identidades gerenciadas atribuídas pelo sistema, você não precisa fornecer um valor para a msiClientId propriedade. O serviço de registro de dados usa automaticamente a identidade atribuída ao sistema da conta do Azure Maps quando msiClientId é nulo.

atribuído pelo usuário

O valor usado para a msiClientId propriedade é o ID do cliente de uma identidade gerenciada atribuída ao usuário.

1. Na sua conta do Azure Maps, selecione Identidade no menu à esquerda.

2. Passe o cursor sobre o nome da identificação gerenciada até que ela apareça como um link e selecione-a.

   

3. Copie a ID do cliente.

   

A propriedade blobUrl

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

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

2. Selecione Contêineres no menu à esquerda.

3. É apresentada uma lista de contentores. Selecione o contêiner que contém o arquivo que você deseja registrar.

4. O contêiner é aberto, mostrando uma lista dos arquivos carregados anteriormente.

5. Selecione o arquivo desejado e copie o URL.

   

O ID de dados do usuário

O ID de dados do usuário (udid) do registro de dados é um GUID definido pelo usuário que deve 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}$

Gorjeta

O udid é um GUID definido pelo usuário que deve ser fornecido ao criar um registro de dados. Se você quiser ter certeza de que tem um identificador global exclusivo (GUID), considere criá-lo executando uma ferramenta de geração de GUID, como o programa de linha de comando Guidgen.exe (Disponível com o Visual Studio).

Criar um registo de dados

Agora que você tem sua conta de armazenamento com os arquivos desejados vinculados à sua conta do Azure Maps por meio do armazenamento de dados e reuniu todas as propriedades necessárias, está pronto para usar a API de registro de dados para registrar esses arquivos. Se você tiver vários arquivos em sua conta de armazenamento do Azure que deseja registrar, precisará executar a solicitação de registro para cada arquivo (udid).

Nota

O tamanho máximo de um arquivo que pode ser registrado em um armazenamento de dados do Azure Maps é de um gigabyte.

Para criar um registo de dados:

atribuído pelo sistema

1. Forneça as informações necessárias para fazer referência à conta de armazenamento que está sendo adicionada ao registro de dados no corpo da sua solicitação HTTP. As informações devem estar no formato JSON e conter os seguintes campos:

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

   Nota

   Ao usar identidades gerenciadas atribuídas pelo sistema, você receberá um erro se fornecer um valor para a propriedade msiClientId em sua solicitação HTTP.

   Para obter mais informações sobre as propriedades necessárias no corpo da solicitação HTTP, consulte Propriedades do Registro de dados.

2. Depois de ter o corpo da sua solicitação HTTP pronto, execute a seguinte solicitação HTTP PUT:

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

   Para obter mais informações sobre a propriedade, consulte A ID de dados do udid usuário.

3. Copie o valor da chave Operation-Location do cabeçalho da resposta.

atribuído pelo usuário

1. Forneça as informações necessárias para fazer referência à conta de armazenamento que está sendo adicionada ao registro de dados no corpo da sua solicitação HTTP. As informações devem estar no formato JSON e conter os seguintes campos:

   {
   "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"
       }
   }
   

   Nota

   Ao usar identidades gerenciadas atribuídas pelo usuário, você receberá um erro se não fornecer um valor para a propriedade msiClientId em sua solicitação HTTP.

   Para obter mais informações sobre as propriedades necessárias no corpo da solicitação HTTP, consulte Propriedades do Registro de dados.

2. Depois de ter o corpo da sua solicitação HTTP pronto, execute a seguinte solicitação HTTP PUT:

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

   Para obter mais informações sobre a propriedade, consulte A ID de dados do udid usuário.

3. Copie o valor da chave Operation-Location do cabeçalho da resposta.

Gorjeta

Se o conteúdo de um arquivo registrado anteriormente for modificado, ele falhará na validação de dados e não poderá ser usado no Azure Maps até ser registrado novamente. Para registrar novamente um arquivo, execute novamente a solicitação de registro, passando o mesmo AzureBlob usado para criar o registro original. O valor da chave Operation-Location é a URL de status que você usará para verificar o status da criação do registro de dados na próxima seção, ela contém a ID da operação usada pela API de operação Get.

Nota

O valor da chave Operation-Location não conterá o subscription-key, você precisará adicioná-lo à URL da solicitação ao usá-la para verificar o status de criação do registro de dados.

Verificar o estado de criação do registo 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 sua chave de assinatura como um parâmetro de cadeia de caracteres de consulta. A solicitação deve ser semelhante ao 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 ficheiros no registo de dados

Use a solicitação Lista para obter uma lista de todos os arquivos registrados em uma conta do Azure Maps:

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ído, 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 lista são semelhantes aos dados fornecidos ao criar um registro com algumas adições:

propriedade	descrição
conteúdoMD5	Hash MD5 criado a partir do conteúdo do arquivo que está sendo registrado. Para obter mais informações, consulte Validação de dados
sizeInBytes	O tamanho do conteúdo em bytes.

Substituir um registo de dados

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

Validação de dados

Quando você registra um arquivo no Azure Maps usando a API de registro de dados, um hash MD5 é criado a partir do conteúdo do arquivo, codificando-o em uma impressão digital de 128 bits e salvando-o AzureBlob na como a contentMD5 propriedade. O hash MD5 armazenado na contentMD5 propriedade é usado para garantir a integridade dos dados do arquivo. Como o algoritmo de hash MD5 sempre produz a mesma saída dada a mesma entrada, o processo de validação de dados pode comparar a contentMD5 propriedade do arquivo quando ele foi registrado com um hash do arquivo na conta de armazenamento do Azure para verificar se ele está intacto e não modificado. 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 falhará. Se você precisar modificar o conteúdo de um arquivo que foi registrado no Azure Maps, precisará registrá-lo novamente.