Créer un 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.

• La propriété metadata spécifie le chemin d'accès à un fichier qui indique le type de données à importer : 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 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 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, lorsque les données sont en cours de traitement, 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 que l'importation réussisse, le state du jeu de données doit être 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 vous 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 propriété errorMessage unique 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)"
    },
    ...
  ]
}

Si le nombre d'erreurs est supérieur à 50 (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, cela signifie qu'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 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 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 de celui-ci. 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 depuis un fichier, et spécifiez les nouvelles données à importer.

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

• 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 qui a été déployée avec succès reste la version "active" et est celle utilisée par votre application.