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 le jeu de données pour créer une nouvelle version du jeu de données.

Créer l'ensemble de données

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

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

Transmettez un corps JSON. à la requête qui définit 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, sous la forme 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 envoyez des requêtes à mettre à jour ou modifier 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éé le jeu de données, importez les données depuis Google Cloud Storage ou depuis un fichier local vers l'ensemble de données.

L'opération d'importation est asynchrone. Une fois les données importées, elles sont ingérés et traités. Cela signifie que vous devez effectuer une requête HTTP GET pour surveiller l'état du jeu de données afin de déterminer quand il est prêt à être utilisé ou si des erreurs se sont produites. Pour en savoir plus, consultez Obtenir le traitement des données l'état.

Importer des données depuis Cloud Storage

Pour importer des données dans votre ensemble de données depuis Cloud Storage, envoyez une requête POST au d'ensembles de données, inclut 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 suivant : gs://GCS_BUCKET/FILE

    L'utilisateur qui effectue la requête a besoin que l'objet Storage Lecteur ou tout autre rôle incluant l'autorisation storage.objects.get. Pour plus d'informations 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 d'ensembles de données, inclut 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.

  • La propriété metadata spécifiant le chemin d'accès à un fichier spécifiant le Type de données à importer, au format suivant: 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"}}

  • La 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 :

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

Obtenir l'état du traitement des données

L'opération d'importation est asynchrone. Cela signifie qu'après l'appel d'API pour importer les données renvoyées par le jeu de données, vous devez ensuite interroger l'ensemble de données pour déterminer si l'ingestion et le traitement des données ont réussi ou échoué.

Pour déterminer le state de la utilisez l'option Obtenir un ensemble de données. Par exemple, pendant que les données sont traité, state est défini sur STATE_PROCESSING. Lorsque l'ensemble de données est prêt à utiliser dans votre application, state est défini sur STATE_COMPLETED.

Par exemple, effectuez un appel GET sur l'ensemble de données:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"

Pour une importation réussie, le state de l'ensemble de données est STATE_COMPLETED:

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_COMPLETED",
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

En cas d'échec du traitement des données, state est défini sur une valeur autre que STATE_COMPLETED, tel que STATE_PUBLISHING_FAILED ou tout état se terminant par _FAILED.

Par exemple, vous téléchargez des données dans un jeu de données, puis vous créez une requête GET pour obtenir les détails de l'ensemble de données. Avec la propriété state, La réponse inclut également une seule propriété errorMessage contenant une description de l'erreur.

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_PUBLISHING_FAILED",
    "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)"
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

Obtenir les erreurs de traitement des données

En cas d'échec de l'ingestion et du traitement des données, la propriété errorMessage contient une un seul message décrivant l'erreur. Toutefois, un seul message d'erreur ne fournit pas toujours suffisamment d'informations pour identifier et résoudre les problèmes.

Pour obtenir des informations complètes sur les erreurs, appelez la méthode fetchDatasetErrors API. Cette API renvoie toutes les erreurs de traitement des données associées à un ensemble de données:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"

La réponse contient le tableau errors. Ce tableau contient jusqu'à 50 erreurs de saisissez Status par appel et prend en charge jusqu'à 500 erreurs au total:

{
  "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj",
  "errors": [
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)"
    },
    ...
  ]
}

S'il y a plus de 50 erreurs, c'est-à-dire si plus d'une page de s'affiche, la réponse contient un jeton de page dans le champ nextPageToken. Transmettez cette valeur dans le paramètre de requête pageToken d'un appel ultérieur pour obtenir la page d'erreurs suivante. Lorsque nextPageToken est vide, il n'y a plus de pages.

Par exemple, pour obtenir la page d'erreurs suivante en utilisant le jeton de l'étape précédente, réponse:

curl -X GET \
  -H "content-type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"

Par défaut, la réponse contient un maximum de 50 erreurs par page. Utilisez le paramètre de requête pageSize pour contrôler la taille de la page.

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 le jeu de données est prêt à utiliser 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 le jeu de données pour créer une nouvelle version du ensemble de données. Pour importer de nouvelles données, suivez le même processus que pour importer des données. depuis Cloud Storage ou importer des données à partir d'un fichier, et spécifiez 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 il s'agit de la version utilisée par votre l'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 "active" et est la version utilisée par votre application.