Como criar o registo de dados
O serviço de registo de dados permite-lhe registar conteúdos de dados numa Conta de Armazenamento do Azure com a sua conta Azure Maps. Um exemplo de dados pode incluir uma coleção de Geofences utilizada no serviço geofencing Azure Maps. Outro exemplo são os ficheiros ZIP que contêm pacotes de desenho (DWG) ou ficheiros GeoJSON que Azure Maps o Criador utiliza para criar ou atualizar mapas interiores.
Pré-requisitos
Importante
- Este artigo utiliza o
us.atlas.microsoft.comURL geográfico. Se a sua conta não tiver sido criada no Estados Unidos, tem de utilizar um URL geográfico diferente. Para obter mais informações, veja Access to Creator services (Acesso aos serviços do Criador). - Nos exemplos de URL neste artigo, terá de substituir:
{Azure-Maps-Subscription-key}com a sua chave de subscrição Azure Maps.{udid}com o ID de dados de utilizador do seu registo de dados. Para obter mais informações, veja O ID de dados do utilizador.
Preparar para registar dados no Azure Maps
Antes de poder registar dados no Azure Maps, tem de criar um ambiente que contenha todos os componentes necessários. Precisa de uma conta de armazenamento com um ou mais contentores que contêm os ficheiros que pretende registar e as identidades geridas para autenticação. Esta secção explica como preparar o ambiente do Azure para registar dados no Azure Maps.
Criar identidades geridas
Existem dois tipos de identidades geridas: atribuídas pelo sistema e atribuídas pelo utilizador. As identidades geridas atribuídas pelo sistema têm o ciclo de vida associado ao recurso que as criou. As identidades geridas atribuídas pelo utilizador podem ser utilizadas em vários recursos. Para obter mais informações, veja Identidades geridas para recursos do Azure.
Utilize os seguintes passos para criar uma identidade gerida e adicioná-la à sua conta Azure Maps.
Criar uma identidade gerida atribuída pelo sistema:
- Aceda à sua conta de Azure Maps no portal do Azure.
- Selecione Identidade no menu esquerdo.
- Alterne o Estado para Ativado.
Para obter mais informações, veja Identidades geridas para recursos do Azure.
Criar um contentor e carregar ficheiros de dados
Antes de adicionar ficheiros a um registo de dados, tem de os carregar para um contentor na sua conta de armazenamento do Azure. Os contentores são semelhantes a um diretório num sistema de ficheiros, são como os seus ficheiros são organizados na sua conta de armazenamento do Azure.
Para criar um contentor no portal do Azure, siga estes passos:
Na sua conta de armazenamento do Azure, selecione Contentores na secção Armazenamento de dados no painel de navegação.
Selecione + Contentor no painel Contentores para apresentar o painel Novo contentor .
Selecione Criar para criar o contentor.
Assim que o contentor tiver sido criado, pode carregar ficheiros para o mesmo.
Assim que o contentor for criado, selecione-o.
Selecione Carregar na barra de ferramentas e selecione um ou mais ficheiros
Selecione o botão Carregar.
Adicionar um arquivo de dados
Depois de criar uma conta de armazenamento do Azure com ficheiros carregados para um ou mais contentores, está pronto para criar o arquivo de dados que liga as contas de armazenamento à sua conta de Azure Maps.
Importante
Todas as contas de armazenamento ligadas a uma conta Azure Maps têm de estar na mesma localização geográfica. Para obter mais informações, veja Azure Maps âmbito geográfico do serviço.
Nota
Se não tiver uma conta de armazenamento, consulte Criar uma conta de armazenamento.
Selecione Arquivo de dados no menu esquerdo da sua conta Azure Maps.
Selecione o botão Adicionar . É apresentado um ecrã Adicionar arquivo de dados no lado direito.
Introduza o ID do Arquivo de Dados pretendido e, em seguida, selecione o Nome da subscrição e a Conta de armazenamento nas listas pendentes.
Selecione Adicionar.
O novo arquivo de dados aparece agora na lista de arquivos de dados.
Atribuir funções a identidades geridas e adicioná-las ao arquivo de dados
Assim que as identidades geridas e o arquivo de dados forem criados, pode adicionar as identidades geridas ao arquivo de dados e atribuir-lhes simultaneamente as funções Contribuidor e Leitor de Dados de Blobs de Armazenamento . Embora seja possível adicionar funções às suas identidades geridas diretamente nas identidades geridas ou na conta de armazenamento, o que pode fazer facilmente ao associá-las ao Azure Maps arquivo de dados diretamente no painel do arquivo de dados.
Nota
Cada identidade gerida associada ao arquivo de dados precisará das funções Contribuidor e Leitor de Dados de Blobs de Armazenamento concedidas às mesmas. Se não tiver as permissões necessárias para conceder funções a identidades geridas, consulte o administrador do Azure. Para atribuir funções às suas identidades geridas e associá-las a um arquivo de dados:
Selecione Arquivo de Dados no menu esquerdo da sua conta Azure Maps.
Selecione um ou mais arquivos de dados na lista e, em seguida, Atribuir funções.
Selecione a Identidade gerida a associar aos arquivos de dados selecionados na lista pendente.
Selecione Contribuidor e Leitor de Dados de Blobs de Armazenamento na lista pendente Funções a atribuir .
Selecione o botão Atribuir .
Propriedades do registo de dados
Com um arquivo de dados criado na sua conta Azure Maps, está pronto para recolher as propriedades necessárias para criar o registo de dados.
Existem as propriedades do AzureBlob que transmite no corpo do pedido HTTP e o ID de dados de utilizador transmitido no URL.
O AzureBlob
É AzureBlob um objeto JSON que define as propriedades necessárias para criar o registo de dados.
| Propriedade | Descrição |
|---|---|
kind |
Define que tipo de objeto está a ser registado. Atualmente, o AzureBlob é o único tipo que é suportado. |
dataFormat |
O formato de dados do ficheiro localizado no blobUrl. O seu formato pode ser GeoJSON para o serviço espacial ou ZIP para o serviço de conversão. |
msiClientId |
O ID da identidade gerida que está a ser utilizada para criar o registo de dados. |
linkedResource |
O ID do arquivo de dados registado na conta Azure Maps. O arquivo de dados contém uma ligação para o ficheiro que está a ser registado. |
blobUrl |
Um URL a apontar para a Localização do AzurebBlob, o ficheiro importado para o contentor. |
As duas secções seguintes fornecem detalhes sobre como obter os valores a utilizar para as propriedades msiClientId e blobUrl .
A propriedade msiClientId
A msiClientId propriedade é o ID da identidade gerida utilizada para criar o registo de dados. Existem dois tipos de identidades geridas: atribuídas pelo sistema e atribuídas pelo utilizador. As identidades geridas atribuídas pelo sistema têm o ciclo de vida associado ao recurso que as criou. As identidades geridas atribuídas pelo utilizador podem ser utilizadas em vários recursos. Para obter mais informações, veja Identidades geridas para recursos do Azure.
Ao utilizar identidades geridas atribuídas pelo sistema, não precisa de fornecer um valor para a msiClientId propriedade. O serviço de registo de dados utiliza automaticamente a identidade atribuída pelo sistema da conta Azure Maps quando msiClientId é nulo.
A propriedade blobUrl
A blobUrl propriedade é o caminho para o ficheiro que está a ser registado. Pode obter este valor a partir do contentor ao qual foi adicionado. registo de dados
Selecione a sua conta de armazenamento no portal do Azure.
Selecione Contentores no menu esquerdo.
É apresentada uma lista de contentores. Selecione o contentor que contém o ficheiro que pretende registar.
O contentor é aberto, mostrando uma lista dos ficheiros carregados anteriormente.
Selecione o ficheiro pretendido e, em seguida, copie o URL.
O ID de dados do utilizador
O ID de dados do utilizador (udid) do registo de dados é um GUID definido pelo utilizador que tem de 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 utilizador que tem de ser fornecido ao criar um registo de dados. Se quiser ter a certeza de que tem um identificador exclusivo global (GUID), considere criá-lo ao executar uma ferramenta de geração de GUID, como o programa de linha de comandos Guidgen.exe (Disponível com o Visual Studio).
Criar um registo de dados
Agora que tem a sua conta de armazenamento com os ficheiros pretendidos associados à sua conta de Azure Maps através do arquivo de dados e que recolheu todas as propriedades necessárias, está pronto para utilizar a API de registo de dados para registar esses ficheiros. Se tiver vários ficheiros na sua conta de armazenamento do Azure que pretende registar, terá de executar o pedido de registo para cada ficheiro (udid).
Nota
O tamanho máximo de um ficheiro que pode ser registado num arquivo de dados Azure Maps é um gigabyte.
Para criar um registo de dados:
Forneça as informações necessárias para referenciar a conta de armazenamento que está a ser adicionada ao registo de dados no corpo do seu pedido HTTP. As informações têm de 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 utilizar identidades geridas atribuídas pelo sistema, receberá um erro se fornecer um valor para a propriedade msiClientId no seu pedido HTTP.
Para obter mais informações sobre as propriedades necessárias no corpo do pedido HTTP, veja Propriedades do registo de dados.
Assim que tiver o corpo do pedido HTTP pronto, execute o seguinte pedido 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
udidpropriedade, veja O ID de dados do utilizador.Copie o valor da chave Operation-Location do cabeçalho de resposta.
Dica
Se o conteúdo de um ficheiro registado anteriormente for modificado, falhará a validação de dados e não será utilizável no Azure Maps até ser novamente registado. Para voltar a registar um ficheiro, execute novamente o pedido de registo, transmitindo o mesmo AzureBlob utilizado para criar o registo original. O valor da chave Operation-Location é o URL de estado que irá utilizar para verificar o estado da criação do registo de dados na próxima secção, que contém o ID de operação utilizado pela API de operação Obter .
Nota
O valor da chave Operation-Location não irá conter o subscription-key, terá de adicioná-lo ao URL do pedido ao utilizá-lo para verificar o estado de criação do registo de dados.
Verificar o estado de criação do registo de dados
Para (opcionalmente) verificar o estado do processo de criação do registo de dados, introduza o URL de estado que copiou na secção Criar um registo de dados e adicione a chave de subscrição como um parâmetro de cadeia de consulta. O pedido deve ter um aspeto 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
Utilize o pedido Lista para obter uma lista de todos os ficheiros registados numa conta Azure Maps:
https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}
O exemplo seguinte demonstra três estados possíveis, concluídos, em execução e com falhas:
{
"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 devolvidos ao executar o pedido de lista são semelhantes aos dados fornecidos ao criar um registo com algumas adições:
| property | descrição |
|---|---|
| contentMD5 | Hash MD5 criado a partir do conteúdo do ficheiro que está a ser registado. Para obter mais informações, veja Validação de dados |
| sizeInBytes | O tamanho do conteúdo em bytes. |
Substituir um registo de dados
Se precisar de substituir um ficheiro registado anteriormente por outro ficheiro, execute novamente o pedido de registo, transmitindo o mesmo AzureBlob utilizado para criar o registo original, exceto o blobUrl. Tem BlobUrl de ser modificado para apontar para o novo ficheiro.
Validação de dados
Quando regista um ficheiro no Azure Maps através da API de registo de dados, é criado um hash MD5 a partir do conteúdo do ficheiro, codificando-o numa impressão digital de 128 bits e guardando-o AzureBlob na propriedade .contentMD5 O hash MD5 armazenado na contentMD5 propriedade é utilizado para garantir a integridade dos dados do ficheiro. Uma vez que o algoritmo hash MD5 produz sempre a mesma saída dada a mesma entrada, o processo de validação de dados pode comparar a contentMD5 propriedade do ficheiro quando foi registado num hash do ficheiro na conta de armazenamento do Azure para verificar se está intacto e não modificado. Se o hash não for o mesmo, a validação falhará. Se o ficheiro na conta de armazenamento subjacente for alterado, a validação falhará. Se precisar de modificar o conteúdo de um ficheiro registado no Azure Maps, terá de registá-lo novamente.