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
Importante
- Este artigo usa a URL geográfica
us.atlas.microsoft.com. Se a conta não tiver sido criada no Estados Unidos, use uma URL geográfica diferente. Para saber mais, confira Acesso aos serviços de Criador. - Nos exemplos de URL neste artigo, você precisará substituir:
{Azure-Maps-Subscription-key}com a chave de assinatura do Azure Mapas.{udid}com a ID de dados do usuário do registro de dados. Para obter mais informações, confira A ID de dados do usuário.
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.
Criar uma identidade gerenciada atribuída pelo sistema:
- Acesse sua conta do Azure Mapas no portal do Azure.
- Selecione Identidade no menu esquerdo.
- Mude o Status para Ativado.
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:
Na conta de armazenamento do Azure, selecione Contêineres na seção Armazenamento de dados no painel de navegação.
Selecione + Contêiner no painel Contêineres para abrir o painel Novo contêiner.
Selecione Criar para criar o contêiner.
Depois que o contêiner for criado, você poderá carregar arquivos nele.
Depois que o contêiner for criado, selecione-o.
Selecione Carregar na barra de ferramentas e escolha um ou mais arquivos
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.
Importante
Todas as contas de armazenamento vinculadas a uma conta do Azure Mapas precisam estar na mesma localização geográfica. Para obter mais informações, confira Escopo geográfico do serviço do Azure Mapas.
Observação
Se você não tiver uma conta de armazenamento, confira Criar uma conta de armazenamento.
Selecione Armazenamento de dados no menu à esquerda na conta do Azure Mapas.
Selecione o botão Adicionar. Uma tela Adicionar armazenamento de dados é exibida no lado direito.
Insira a ID do armazenamento de dados desejada e selecione o Nome da assinatura e a Conta de armazenamento nas listas suspensas.
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.
Observação
Cada identidade gerenciada associada ao armazenamento de dados precisará receber as funções Colaborador e Leitor de Dados do Blob de Armazenamento. Se você não tiver as permissões necessárias para conceder funções a identidades gerenciadas, fale com o administrador do Azure. Para atribuir funções às identidades gerenciadas e associá-las a um armazenamento de dados:
Selecione Armazenamento de dados no menu à esquerda na conta do Azure Mapas.
Selecione um ou mais armazenamentos de dados na lista e clique em Atribuir funções.
Selecione a Identidade gerenciada a ser associada aos armazenamentos de dados selecionados na lista suspensa.
Selecione Colaborador e Leitor de Dados do Blob de Armazenamento na lista suspensa Funções a serem atribuídas.
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.
| Propriedade | Descrição |
|---|---|
kind |
Define que tipo de objeto está sendo registrado. No momento, AzureBlob é o único tipo com suporte. |
dataFormat |
O formato de dados do arquivo localizado na blobUrl. O formato pode ser GeoJSON para o serviço espacial ou ZIP para o serviço de conversão. |
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 Mapas. O armazenamento de dados contém um link para o arquivo que está sendo registrado. |
blobUrl |
Uma URL que aponta para o local do AzurebBlob, o arquivo importado no contêiner. |
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.
Ao usar identidades gerenciadas atribuídas pelo sistema, você não precisa fornecer um valor para a propriedade msiClientId. O serviço de registro de dados usa automaticamente a identidade atribuída pelo sistema da conta do Azure Mapas quando msiClientId for nulo.
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
Selecione a conta de armazenamento no portal do Azure.
Selecione Contêineres no menu à esquerda.
Uma lista de contêineres é exibida. Selecione o contêiner que contém o arquivo que você deseja registrar.
O contêiner é aberto, mostrando uma lista dos arquivos que já foram carregados.
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}$
Dica
O udid é um GUID definido pelo usuário que precisa ser fornecido durante a criação de um registro de dados. Caso você deseje ter certeza de que tem um GUID (identificador global exclusivo), considere criá-lo executando uma ferramenta de geração de GUID, como o programa de linha de comando Guidgen.exe (disponível no Visual Studio).
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).
Observação
O tamanho máximo de um arquivo que pode ser registrado com um armazenamento de dados do Azure Mapas é de um gigabyte.
Para criar um registro de dados:
Forneça as informações necessárias para referenciar a conta de armazenamento que está sendo adicionada ao registro de dados no corpo da 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" } }Observação
Ao usar as identidades gerenciadas atribuídas pelo sistema, você receberá um erro se fornecer um valor para a propriedade msiClientId na sua solicitação HTTP.
Para obter mais informações sobre as propriedades necessárias no corpo da solicitação HTTP, confira Propriedades do registro de dados.
Depois de preparar o corpo da solicitação HTTP, 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
udid, confira A ID de dados do usuário.Copie o valor da chave Operation-Location do cabeçalho de resposta.
Dica
Se o conteúdo de um arquivo já registrado for modificado, ele falhará na validação de dados e não poderá ser usado no Azure Mapas até que seja 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, que contém a ID da operação usada pela API da operação Get.
Observação
O valor da chave Operation-Location não conterá o subscription-key. Você precisará adicioná-lo à URL de solicitação ao usá-la para verificar o status de criação do 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:
| propriedade | descrição |
|---|---|
| contentMD5 | O hash MD5 criado com base no conteúdo do arquivo que está sendo registrado. Para obter mais informações, confira Validação de dados |
| sizeInBytes | O tamanho do conteúdo em bytes. |
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.