Cette page a été traduite par l'API Cloud Translation.

Créer un ensemble de données

La création d'un ensemble de données se fait en deux étapes :

Envoyez une requête pour créer l'ensemble de données.
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 pour créer une nouvelle version.

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.

Remarque : USAGE_DATA_DRIVEN_STYLING est la seule valeur acceptée pour usage.

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 pour 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éé l'ensemble de données, importez-y les données à partir de Google Cloud Storage ou d'un fichier local.

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

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 qui spécifie 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"
}

Obtenir l'état du traitement des données

L'opération d'importation est asynchrone. Cela signifie qu'une fois que l'appel d'API pour importer les données dans l'ensemble de données est renvoyé, vous devez 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 la state de l'ensemble de données, utilisez Obtenir un ensemble de données. Par exemple, pendant le traitement des données, state est défini sur STATE_PROCESSING. Lorsque l'ensemble de données est prêt à être utilisé 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, telle que STATE_PUBLISHING_FAILED ou tout état se terminant par la chaîne _FAILED.

Par exemple, vous importez des données dans un ensemble de données, puis effectuez une requête GET pour obtenir les détails de l'ensemble de données. En plus de 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

Lorsque l'ingestion et le traitement des données échouent, la propriété errorMessage contient un seul message décrivant l'erreur. Toutefois, un seul message d'erreur ne fournit pas nécessairement suffisamment d'informations pour identifier et résoudre les problèmes.

Pour obtenir des informations complètes sur les erreurs, appelez l'API fetchDatasetErrors. 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 type Status par appel et accepte 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 plus d'une page d'erreurs, 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 la réponse précédente:

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 50 erreurs maximum 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 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.