Créer un ensemble de données

La création d'un ensemble de données s'effectue en deux étapes:

  1. Envoyez une requête pour créer l'ensemble de données.

  2. Envoyez une requête pour importer des données dans l'ensemble de données.

Après l'importation initiale des données, vous pouvez importer de nouvelles données dans l'ensemble de données afin d'en créer une nouvelle version.

Conditions préalables

Lorsque vous créez un ensemble de données :

  • Les noms à afficher doivent être uniques au sein de votre projet Google Cloud.
  • Les noms à afficher doivent comprendre moins de 64 octets (ces caractères étant représentés au format UTF-8, chaque caractère peut correspondre à plusieurs octets dans certaines langues).
  • Les descriptions doivent comprendre moins de 1 000 octets.

Lorsque vous importez des données :

  • Les types de fichiers CSV, GeoJSON et KML sont acceptés.
  • La taille maximale autorisée pour les fichiers est de 350 Mo.
  • Les noms de colonnes d'attributs ne peuvent pas commencer par la chaîne "?_".
  • Les géométries tridimensionnelles ne sont pas acceptées. Cela inclut le suffixe "Z" au format WKT et les coordonnées d'altitude au format GeoJSON.

Bonnes pratiques pour la préparation des données

Si vos données sources sont complexes ou volumineuses, telles que des points denses, des longues polylignes ou des polygones (souvent des fichiers sources de taille supérieure à 50 Mo entrent dans cette catégorie), envisagez de simplifier vos données avant de les importer pour obtenir les meilleures performances sur une carte visuelle.

Voici quelques bonnes pratiques pour préparer vos données:

  1. Réduire les propriétés de l'élément géographique. Ne conservez que les propriétés d'éléments géographiques nécessaires pour appliquer un style à votre carte (par exemple, "id" et "category"). Vous pouvez associer des propriétés supplémentaires à une fonctionnalité d'une application cliente en utilisant des styles basés sur les données sur une clé d'identifiant unique. Par exemple, consultez la section Afficher vos données en temps réel grâce au style basé sur les données.
  2. Dans la mesure du possible, utilisez des types de données simples pour les objets de propriété, tels que des entiers, afin de réduire la taille des tuiles et d'améliorer les performances de la carte.
  3. Simplifier les géométries complexes avant d'importer un fichier. Vous pouvez le faire dans l'outil géospatial de votre choix, tel que l'utilitaire Open Source Mapshaper.org, ou dans BigQuery en utilisant ST_Simplify sur des géométries de polygones complexes.
  4. Regroupez les points très denses avant d'importer un fichier. Vous pouvez le faire dans l'outil géospatial de votre choix, tel que les fonctions de cluster turf.js Open Source, ou dans BigQuery en utilisant ST_CLUSTERDBSCAN sur les géométries de points denses.

Pour obtenir des conseils supplémentaires sur les bonnes pratiques concernant les ensembles de données, consultez la page Visualiser vos données avec des ensembles de données et BigQuery.

Exigences du format GeoJSON

L'API Maps Datasets est compatible avec la spécification GeoJSON actuelle. L'API Maps Datasets est également compatible avec les fichiers GeoJSON contenant l'un des types d'objets suivants:

  • Objets Geometry : un objet Geometry est une forme spatiale, décrite comme une union de points, de lignes et de polygones avec facultativement des trous.
  • Objets Feature : un objet Feature contient une géométrie et des paires nom/valeur supplémentaires, dont la signification dépend de l'application.
  • Collections d'éléments géographiques : une collection d'éléments géographiques est un ensemble d'objets Feature.

L'API Maps Datasets n'est pas compatible avec les fichiers GeoJSON contenant des données dans un système de coordonnées de référence (CRS) autre que WGS84.

Pour en savoir plus sur GeoJSON, consultez la page sur la conformité RFC 7946.

Exigences du format KML

La configuration requise pour l'API Maps Datasets est la suivante:

  • Toutes les URL doivent être locales (ou relatives) par rapport au fichier lui-même.
  • Les géométries acceptées sont les points, les lignes et les polygones.
  • Tous les attributs de données sont considérés comme des chaînes.
Les éléments géographiques KML suivants ne sont pas acceptés :
  • Icônes ou <styleUrl> définis en dehors du fichier
  • Liens réseau tels que <NetworkLink>
  • Superpositions au sol telles que <GroundOverlay>
  • Géométries 3D ou toute balise d'altitude telle que <altitudeMode>
  • Spécifications concernant la prise de vue telles que <LookAt>
  • Styles définis dans le fichier KML

Exigences du format CSV

Pour les fichiers CSV, les noms de colonnes acceptés sont indiqués ci-dessous par ordre de priorité :

  • latitude, longitude
  • lat, long
  • x, y
  • wkt (Well-Known Text)
  • address, city, state et zip
  • address
  • Une seule colonne contenant toutes les informations d'adresse telles que 1600 Amphitheatre Parkway Mountain View, CA 94043

Par exemple, votre fichier contient des colonnes nommées x, y et wkt. Étant donné que x et y ont une priorité plus élevée d'après l'ordre des noms de colonnes acceptés dans la liste ci-dessus, les valeurs des colonnes x et y sont utilisées, et la colonne wkt est ignorée.

En outre :

  • Chaque nom de colonne doit appartenir à une seule colonne. Autrement dit, vous ne pouvez pas avoir de colonne nommée xy contenant à la fois les coordonnées x et y. Les coordonnées x et y doivent se trouver dans des colonnes distinctes.
  • Les noms de colonnes ne sont pas sensibles à la casse.
  • L'ordre des noms de colonnes n'a pas d'importance. Par exemple, si votre fichier CSV contient les colonnes lat et long, elles peuvent apparaître dans n'importe quel ordre.

Gérer les erreurs d'importation de données

Lorsque vous importez des données dans un ensemble de données, vous pouvez rencontrer l'une des erreurs courantes décrites dans cette section.

Erreurs GeoJSON

Voici quelques erreurs GeoJSON courantes :

  • Champ type manquant, ou bien le type n'est pas une chaîne. Le fichier de données GeoJSON importé doit contenir un champ de type chaîne nommé type dans chaque définition d'objet Feature et Geometry.

Erreurs KML

Voici quelques erreurs KML courantes :

  • Le fichier de données ne doit contenir aucun des éléments géographiques KML non acceptés dont la liste figure plus haut dans ce document. Sinon, l'importation des données risque d'échouer.

Erreurs CSV

Voici quelques erreurs CSV courantes :

  • Certaines lignes ne contiennent aucune valeur dans une colonne de géométrie. Toutes les lignes d'un fichier CSV doivent contenir des valeurs non vides pour les colonnes de géométrie. Les colonnes de géométrie incluent :
    • latitude, longitude
    • lat, long
    • x, y
    • wkt
    • address, city, state et zip
    • address
    • Une seule colonne contenant toutes les informations d'adresse telles que 1600 Amphitheatre Parkway Mountain View, CA 94043
  • Si x et y sont des colonnes de géométrie, assurez-vous que les unités sont la longitude et la latitude. Certains ensembles de données publics utilisent différents systèmes de coordonnées sous les en-têtes x et y. Si vous utilisez des unités incorrectes, l'ensemble de données sera peut-être importé, mais dans le rendu, les points de l'ensemble de données pourront s'afficher à des emplacements inattendus.

Créer l'ensemble de données

Créez un ensemble de données en envoyant une requête POST au point de terminaison datasets:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

Transmettez un corps JSON à la requête définissant l'ensemble de données. Vous devez respecter les points suivants :

  • Spécifiez le displayName de l'ensemble de données. La valeur de displayName doit être unique pour tous les ensembles de données.

  • Définissez usage sur USAGE_DATA_DRIVEN_STYLING.

Exemple :

curl -X POST -d '{
    "displayName": "My Test Dataset", 
    "usage": "USAGE_DATA_DRIVEN_STYLING"
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

La réponse contient l'ID de l'ensemble de données, au format projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID, ainsi que des informations supplémentaires. Utilisez l'ID de l'ensemble de données lorsque vous effectuez des requêtes de mise à jour ou de modification de l'ensemble de données.

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "createTime": "2022-08-15T17:50:00.189682Z",
  "updateTime": "2022-08-15T17:50:00.189682Z" 
}

Importer des données dans le jeu de données

Après avoir créé l'ensemble de données, importez-y les données à partir de Google Cloud Storage ou d'un fichier local.

Importer des données depuis Cloud Storage

Pour importer des données depuis Cloud Storage dans votre ensemble de données, envoyez une requête POST au point de terminaison datasets, qui inclut également l'ID de l'ensemble de données:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

Dans le corps de la requête JSON:

  • Utilisez inputUri pour spécifier le chemin d'accès à la ressource contenant les données dans Cloud Storage. Ce chemin d'accès est au format gs://GCS_BUCKET/FILE.

    L'utilisateur qui effectue la requête doit disposer du rôle Lecteur des objets Storage ou de tout autre rôle comprenant l'autorisation storage.objects.get. Pour en savoir plus sur la gestion de l'accès à Cloud Storage, consultez la page Présentation du contrôle des accès.

  • Utilisez fileFormat pour spécifier le format de fichier des données : FILE_FORMAT_GEOJSON (fichier GeoJson), FILE_FORMAT_KML (fichier KML) ou FILE_FORMAT_CSV (fichier CSV).

Exemple :

curl -X POST  -d '{
    "gcs_source":{
      "inputUri": "gs://my_bucket/my_csv_file",
      "fileFormat": "FILE_FORMAT_CSV"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import

La réponse se présente sous la forme suivante:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

Importer des données à partir d'un fichier

Pour importer des données à partir d'un fichier, envoyez une requête HTTP POST au point de terminaison datasets, qui inclut également l'ID de l'ensemble de données :

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

La requête contient:

  • L'en-tête Goog-Upload-Protocol est défini sur multipart.

  • Propriété metadata spécifiant le chemin d'accès à un fichier spécifiant le type de données à importer, sous la forme FILE_FORMAT_GEOJSON (fichier GeoJSON), FILE_FORMAT_KML (fichier KML) ou FILE_FORMAT_CSV (fichier CSV).

    Le contenu de ce fichier a le format suivant:

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

  • Propriété rawdata spécifiant le chemin d'accès au fichier GeoJSON, KML ou CSV contenant les données à importer.

La requête suivante utilise l'option curl -F pour spécifier le chemin d'accès aux deux fichiers:

curl -X POST \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Goog-Upload-Protocol: multipart" \
  -F "metadata=@csv_metadata_file" \
  -F "rawdata=@csv_data_file" \
  https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import

La réponse se présente sous la forme suivante:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

Importer de nouvelles données dans l'ensemble de données

Une fois que vous avez créé l'ensemble de données et importé les données initiales, l'état de l'ensemble de données est défini sur STATE_COMPLETED. Cela signifie que l'ensemble de données est prêt à être utilisé dans votre application. Pour déterminer la propriété state de l'ensemble de données, consultez la section Obtenir un ensemble de données.

Vous pouvez également importer de nouvelles données dans l'ensemble de données pour créer une nouvelle version de celui-ci. Pour importer de nouvelles données, suivez le même processus que pour importer des données à partir de Cloud Storage ou importer des données à partir d'un fichier, et spécifier les nouvelles données à importer.

Si les nouvelles données sont correctement importées:

  • L'état de la nouvelle version de l'ensemble de données est défini sur STATE_COMPLETED.

  • La nouvelle version devient la version "active" et correspond à la version utilisée par votre application.

Si une erreur se produit lors de l'importation:

  • L'état de la nouvelle version de l'ensemble de données est défini sur l'un des états suivants:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • La version réussie de l'ensemble de données précédent reste la version "active" et correspond à la version utilisée par votre application.