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 l'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 l'ensemble de données

Après avoir créé l'ensemble de données, importez les données dans l'ensemble de 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 envoyer une requête HTTP GET pour surveiller l'état de l'ensemble de données afin de déterminer quand il 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 de Cloud Storage vers 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 des accès à Cloud Storage, consultez 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 est au format suivant:

{
  "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 les éléments suivants:

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 est au format suivant:

{
  "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 l'appel d'API pour importer les données dans l'ensemble de données 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 le 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"

Si l'importation aboutit, la valeur 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
}

Lorsque le traitement des données échoue, 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 des 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 d'erreur complètes, 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 peut contenir 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)"
    },
    ...
  ]
}

Si le nombre d'erreurs est supérieur à 50, ce qui signifie qu'il y a 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 à l'aide du 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, son état 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 le state de l'ensemble de données, consultez 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. Pour importer de nouvelles données, suivez la même procédure que pour importer des données depuis Cloud Storage ou importer des données à partir d'un fichier, puis spécifiez les nouvelles données à importer.

Si les nouvelles données sont bien 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 est celle 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 précédente de l'ensemble de données réussie reste la version "active" et est celle utilisée par votre application.