Creación del registro de datos
El servicio de registro de datos le permite registrar contenido de datos en una cuenta de Azure Storage con su cuenta de Azure Maps. Un ejemplo de datos podría incluir una colección de geovallas utilizadas en el servicio de geovallas de Azure Maps. Otro ejemplo son los archivos ZIP que contienen paquetes de dibujo (DWG) o archivos GeoJSON que Azure Maps Creator utiliza para crear o actualizar mapas interiores.
Requisitos previos
Importante
- En este artículo, se usa la dirección URL geográfica
us.atlas.microsoft.com. Si su cuenta no se creó en la Estados Unidos, debe usar una dirección URL geográfica diferente. Para más información, consulte Acceso a los servicios de Creator. - En los ejemplos de direcciones URL de este artículo, deberá reemplazar:
{Azure-Maps-Subscription-key}con la clave de suscripción de Azure Maps.{udid}con el identificador de datos de usuario de su registro de datos. Para más información, consulte el identificador de datos de usuario.
Preparación para registrar datos en Azure Maps
Para poder registrar datos en Azure Maps, debe crear un entorno que contenga todos los componentes necesarios. Necesita una cuenta de almacenamiento con uno o varios contenedores que contengan los archivos que desea registrar e identidades administradas para la autenticación. En esta sección se explica cómo preparar el entorno de Azure para registrar datos en Azure Maps.
Crear identidades administradas
Hay dos tipos de identidades administradas: asignadas por el sistema y asignadas por el usuario. Las identidades administradas asignadas por el sistema tienen su ciclo de vida vinculado al recurso que las creó. Las identidades administradas asignadas por el usuario se pueden usar en varios recursos. Para más información, consulte Identidades administradas para los recursos de Azure.
Siga estos pasos para crear una identidad administrada y agregarla a la cuenta de Azure Maps.
Crear una identidad administrada asignada por el sistema:
- Vaya a su cuenta de Azure Maps en Azure Portal.
- Seleccione Identidad en el menú izquierdo.
- Cambie el Estado a Activado.
Para más información, consulte Identidades administradas para los recursos de Azure.
Crear un contenedor y cargar archivos de datos
Antes de agregar archivos a un registro de datos, debe cargarlos en un contenedor de la cuenta de almacenamiento de Azure. Los contenedores son similares a un directorio en un sistema de archivos, son la forma en que se organizan los archivos en su cuenta de almacenamiento Azure.
Para crear un contenedor en Azure Portal, siga estos pasos:
En su cuenta de almacenamiento de Azure, seleccione Contenedores en la sección Almacenamiento de datos del panel de navegación.
Seleccione + Contenedor en el panel Contenedores para abrir el panel Nuevo contenedor.
Seleccione Crear para crear el contenedor.
Una vez creado el contenedor, puede cargar archivos en él.
Una vez creado el contenedor, selecciónelo.
Seleccione Cargar en la barra de herramientas, seleccione uno o más archivos
Seleccione el botón Cargar.
Agregar un almacén de datos
Una vez que haya creado una cuenta de almacenamiento de Azure con archivos cargados en uno o varios contenedores, estará listo para crear el almacén de datos que vincula las cuentas de almacenamiento a la cuenta de Azure Maps.
Importante
Todas las cuentas de almacenamiento vinculadas a una cuenta de Azure Maps deben estar en la misma ubicación geográfica. Para obtener más información, consulte Ámbito geográfico del servicio de Azure Maps.
Nota
Si aún no dispone de una cuenta de almacenamiento, vea Crear una cuenta de almacenamiento.
Seleccione Almacén de datos en el menú izquierdo de su cuenta de Azure Maps.
Seleccione el botón Agregar. Aparece una pantalla Agregar almacén de datos en el lado derecho.
Escriba el Id. de almacén de datos deseado y seleccione el Nombre de la suscripción y la Cuenta de almacenamiento en las listas desplegables.
Seleccione Agregar.
El nuevo almacén de datos aparecerá ahora en la lista de almacenes de datos.
Asignar roles a identidades administradas y agregarlos al almacén de datos
Una vez creadas las identidades administradas y el almacén de datos, puede agregar las identidades administradas al almacén de datos y asignarles simultáneamente los roles de Colaborador y Lector de datos del blob de almacenamiento. Aunque es posible agregar roles a las identidades administradas directamente en sus identidades administradas o en la cuenta de almacenamiento, puede hacerlo fácilmente al asociarlos simultáneamente con el almacén de datos de Azure Maps directamente en el panel del almacén de datos.
Nota
Cada identidad administrada asociada al almacén de datos necesitará los roles Colaborador y Lector de datos de blob de almacenamiento concedidos. Si no tiene los permisos necesarios para conceder roles a identidades administradas, consulte al administrador de Azure. Para asignar roles a las identidades administradas y asociarlos a un almacén de datos:
Seleccione Almacén de datos en el menú izquierdo de su cuenta de Azure Maps.
Seleccione uno o varios almacenes de datos de la lista y luego en Asignar roles.
Seleccione la identidad administrada que se va a asociar a los almacenes de datos seleccionados en la lista desplegable.
Seleccione Colaborador y Lector de datos de Storage Blob en la lista desplegable Roles para asigna.
Seleccione el botón Asignar.
Propiedades del registro de datos
Con un almacén de datos creado en la cuenta de Azure Maps, está listo para recopilar las propiedades necesarias para crear el registro de datos.
Están las propiedades de AzureBlob que pasará en el cuerpo de la solicitud HTTP y el id. de datos de usuario pasado en la dirección URL.
The AzureBlob
AzureBlob es un objeto JSON que define las propiedades necesarias para crear el registro de datos.
| Propiedad | Descripción |
|---|---|
kind |
Define qué tipo de objeto se está registrando. Actualmente AzureBlob es el único tipo que se admite. |
dataFormat |
Formato de datos del archivo ubicado en blobUrl. Su formato puede ser GeoJSON para el servicio espacial o ZIP para el servicio de conversión. |
msiClientId |
Id. de la identidad administrada que se usa para crear el registro de datos. |
linkedResource |
Id. del almacén de datos registrado en la cuenta de Azure Maps. El almacén de datos contiene un vínculo al archivo que se está registrando. |
blobUrl |
Dirección URL que apunta a la ubicación de AzurebBlob, el archivo importado en su contenedor. |
En las dos secciones siguientes se proporcionan detalles sobre cómo obtener los valores que se usarán para las propiedades msiClientId y blobUrl.
La propiedad msiClientId
La propiedad msiClientId es el Id. de la identidad administrada que se usa para crear el registro de datos. Hay dos tipos de identidades administradas: asignadas por el sistema y asignadas por el usuario. Las identidades administradas asignadas por el sistema tienen su ciclo de vida vinculado al recurso que las creó. Las identidades administradas asignadas por el usuario se pueden usar en varios recursos. Para más información, consulte Identidades administradas para los recursos de Azure.
Al usar identidades administradas asignadas por el sistema, no es necesario proporcionar un valor para la propiedad msiClientId. El servicio del registro de datos usará automáticamente la identidad asignada por el sistema de la cuenta de Azure Maps cuando msiClientId sea null.
La propiedad blobUrl
La propiedad blobUrl es la ruta de acceso al archivo que se está registrando. Puede obtener este valor del contenedor al que se agregó. registro de datos
Seleccione su cuenta de almacenamiento en Azure Portal.
Seleccione Contenedores en el menú de la izquierda.
Aparecerá una lista de contenedores. Seleccione el contenedor que contiene el archivo que desea registrar.
Se abre el contenedor, que muestra una lista de los archivos cargados anteriormente.
Seleccione el archivo deseado y copie la dirección URL.
Identificador de datos de usuario
El identificador de datos de usuario (udid) del registro de datos es un GUID definido por el usuario que debe cumplir el siguiente patrón 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}$
Sugerencia
udid es un GUID definido por el usuario que se debe proporcionar al crear un registro de datos. Si quiere estar seguro de que tiene un identificador único global (GUID), considere la posibilidad de crearlo mediante la ejecución de una herramienta de generación de GUID como el programa de línea de comandos Guidgen.exe (disponible con Visual Studio).
Crear un registro de datos
Ahora que tiene la cuenta de almacenamiento con los archivos deseados vinculados a la cuenta de Azure Maps a través del almacén de datos y ha recopilado todas las propiedades necesarias, está listo para usar la API del Registro de datos para registrar esos archivos. Si tiene varios archivos en la cuenta de almacenamiento de Azure que desea registrar, deberá ejecutar la solicitud de registro para cada archivo (udid).
Nota
El tamaño máximo de un archivo que se puede registrar con un almacén de datos de Azure Maps es de un gigabyte.
Para crear un registro de datos:
Proporcione la información necesaria para hacer referencia a la cuenta de almacenamiento que se va a agregar al registro de datos en el cuerpo de la solicitud HTTP. La información debe estar en formato JSON y contener los siguientes campos:
{ "kind": "AzureBlob", "azureBlob": { "dataFormat": "geojson", "linkedResource": "{datastore ID}", "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson" } }Nota:
Al usar identidades administradas asignadas por el sistema, obtendrá un error si proporciona un valor para la propiedad msiClientId en la solicitud HTTP.
Para obtener más información sobre las propiedades necesarias en el cuerpo de la solicitud HTTP, consulte Propiedades del registro de datos.
Una vez que tenga listo el cuerpo de la solicitud HTTP, ejecute la siguiente solicitud HTTP PUT:
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}Para obtener más información sobre la propiedad
udid, vea El Id. de datos de usuario.Copie el valor de la clave Operation-Location del encabezado de respuesta.
Sugerencia
Si se modifica el contenido de un archivo registrado anteriormente, se producirá un error en su validación de datos y no se podrá usar en Azure Maps hasta que se vuelva a registrar. Para volver a registrar un archivo, vuelva a ejecutar la solicitud de registro y pase la misma instancia AzureBlob usada para crear el registro original. El valor de la clave Operation-Location es la dirección URL de estado que usará para comprobar el estado de la creación del registro de datos en la siguiente sección, contiene el Id. de operación que usa la API get operation.
Nota
El valor de la clave Operation-Location no contendrá subscription-key, deberá agregarlo a la dirección URL de la solicitud al usarlo para comprobar el estado de creación del registro de datos.
Comprobación del estado de creación del registro de datos
Para comprobar (opcionalmente) el estado del proceso de creación del registro de datos, escriba la dirección URL de estado que copió en la sección Crear un registro de datos y agregue su clave de suscripción como parámetro de cadena de consulta. La solicitud debe tener un aspecto similar al de la siguiente dirección URL:
https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
Obtener una lista de todos los archivos del registro de datos
Para obtener una lista de todos los archivos registrados en una cuenta de Azure Maps mediante la solicitud de Lista:
https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}
A continuación se muestran los tres estados posibles, completado, en ejecución y con errores:
{
"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==."
}
}
]
}
Los datos devueltos al ejecutar la solicitud de lista son similares a los datos proporcionados al crear un registro con algunas adiciones:
| propiedad | description |
|---|---|
| contentMD5 | Hash MD5 creado a partir del contenido del archivo que se está registrando. Para obtener más información, vea Validación de datos. |
| sizeInBytes | Tamaño del contenido en bytes. |
Reemplazar un registro de datos
Si necesita reemplazar un archivo registrado anteriormente por otro archivo, vuelva a ejecutar la solicitud de registro, pasando el mismo AzureBlob usado para crear el registro original, excepto el blobUrl. BlobUrl debe modificarse para que apunte al nuevo archivo.
Validación de datos
Al registrar un archivo en Azure Maps mediante la API del registro de datos, se crea un hash MD5 a partir del contenido del archivo, lo codifica en una huella digital de 128 bits y lo guarda en AzureBlob como propiedad contentMD5. El hash MD5 almacenado en la propiedad contentMD5 se usa para garantizar la integridad de los datos del archivo. Dado que el algoritmo hash MD5 siempre produce la misma salida dada la misma entrada, el proceso de validación de datos puede comparar la propiedad contentMD5 del archivo cuando se registró con un hash del archivo en la cuenta de almacenamiento de Azure para comprobar que está intacto y sin modificar. Si el hash no es el mismo, se producirá un error en la validación. Si el archivo de la cuenta de almacenamiento subyacente cambia, se producirá un error en la validación. Si necesita modificar el contenido de un archivo que se ha registrado en Azure Maps, debe volver a registrarlo.