Crea un set di dati

La creazione di un set di dati è un processo in due fasi:

  1. Effettua una richiesta per creare il set di dati.

  2. Effettua una richiesta per caricare i dati nel set di dati.

Dopo il caricamento iniziale dei dati, puoi caricare nuovi dati nel set di dati per creare una nuova versione del set di dati.

Crea il set di dati

Crea un set di dati inviando una richiesta POST all'oggetto Endpoint set di dati:

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

Trasmettere un corpo JSON. alla richiesta che definisce il set di dati. Devi:

  • Specifica il valore displayName del set di dati. Il valore displayName deve univoco per tutti i set di dati.

  • Imposta usage su USAGE_DATA_DRIVEN_STYLING.

Ad esempio:

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 risposta contiene l'ID del set di dati, nella forma projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID insieme a informazioni aggiuntive. Utilizza l'ID del set di dati quando effettui richieste a aggiornare o modificare il set di dati.

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

Carica i dati nel set di dati

Dopo aver creato il set di dati, carica i dati da Google Cloud Storage o da un file locale al set di dati.

L'operazione di caricamento è asincrona. Una volta caricati, i dati vengono importati ed elaborati. Ciò significa che devi effettuare una richiesta GET HTTP per monitorare lo stato del set di dati per determinare quando è pronto per l'uso o se si sono verificati errori. Per ulteriori informazioni, vedi Ottenere informazioni sull'elaborazione dei dati .

Carica dati da Cloud Storage

Per caricare dati da Cloud Storage al tuo set di dati, invia una richiesta POST all'oggetto dell'endpoint set di dati include l'ID del set di dati:

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

Nel corpo della richiesta JSON:

  • Utilizza inputUri per specificare il percorso del file della risorsa contenente i dati in Cloud Storage. Questo percorso ha il formato gs://GCS_BUCKET/FILE.

    L'utente che effettua la richiesta richiede un oggetto Storage Visualizzatore o qualsiasi altro ruolo che includa l'autorizzazione storage.objects.get. Per per ulteriori informazioni sulla gestione dell'accesso a Cloud Storage, consulta Panoramica del controllo dell'accesso.

  • Utilizza fileFormat per specificare il formato file dei dati come: FILE_FORMAT_GEOJSON (file GeoJson), FILE_FORMAT_KML (file KML) o FILE_FORMAT_CSV (file CSV).

Ad esempio:

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 risposta è nel formato:

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

Caricare dati da un file

Per caricare i dati da un file, invia una richiesta POST HTTP al dell'endpoint set di dati include l'ID del set di dati:

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

La richiesta contiene:

  • L'intestazione Goog-Upload-Protocol è impostata su multipart.

  • La proprietà metadata che specifica il percorso di un file che specifica tipo di dati da caricare, come FILE_FORMAT_GEOJSON (file GeoJSON), FILE_FORMAT_KML (file KML) o FILE_FORMAT_CSV (file CSV).

    I contenuti di questo file hanno il seguente formato:

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

  • La proprietà rawdata che specifica il percorso del file GeoJSON, KML o CSV contenente i dati da caricare.

La seguente richiesta utilizza l'opzione curl -F per specificare il percorso dei due file:

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 risposta è nel formato:

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

Ottieni stato di elaborazione dati

L'operazione di caricamento è asincrona. Ciò significa che, dopo la chiamata API al caricamento, i dati al set di dati restituiti, è necessario eseguire un polling sul set di dati per determinare se l'importazione e l'elaborazione dei dati sono riuscite o non riuscite.

Per determinare la state del usa Ottieni un set di dati. Ad esempio, mentre i dati vengono elaborato, il valore state è impostato su STATE_PROCESSING. Quando il set di dati è pronto da usare nella tua app, il state è impostato su STATE_COMPLETED.

Ad esempio, effettua una chiamata GET sul set di dati:

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"

Per un caricamento riuscito, il state del set di dati è 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
}

Quando l'elaborazione dei dati non riesce, state viene impostato su un valore diverso da STATE_COMPLETED, ad esempio STATE_PUBLISHING_FAILED o qualsiasi stato che termina con stringa _FAILED.

Ad esempio, carichi i dati in un set di dati e quindi effettui un comando GET per ottenere i dettagli del set di dati. Insieme alla proprietà state, il valore la risposta include anche una singola proprietà errorMessage contenente una descrizione dell'errore.

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

Recuperare gli errori di elaborazione dei dati

Quando l'importazione e l'elaborazione dei dati non riescono, la proprietà errorMessage contiene un un singolo messaggio che descrive l'errore. Tuttavia, un singolo messaggio di errore fornire necessariamente informazioni sufficienti per identificare e risolvere i problemi.

Per ottenere informazioni complete sull'errore, chiama il fetchDatasetErrors tramite Google Cloud CLI o tramite l'API Compute Engine. Questa API restituisce tutti gli errori di elaborazione dei dati associati a un set di dati:

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 risposta contiene l'array errors. Questo array contiene fino a 50 errori di digita Status per chiamata e supporta fino a 500 errori in totale:

{
  "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)"
    },
    ...
  ]
}

Se sono presenti più di 50 errori, ovvero più di una pagina di gli errori, la risposta contiene un token di pagina nel campo nextPageToken. Passa questo valore nel parametro di query pageToken di una chiamata successiva per ottenere alla pagina successiva di errori. Quando nextPageToken è vuoto, non ci sono altre pagine.

Ad esempio, per visualizzare la pagina successiva di errori utilizzando il token della precedente risposta:

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"

Per impostazione predefinita, la risposta contiene un massimo di 50 errori per pagina. Utilizza le funzionalità di il parametro di query pageSize per controllare le dimensioni della pagina.

Carica nuovi dati nel set di dati

Dopo aver creato il set di dati e caricato i dati iniziali correttamente, lo stato del set di dati è impostato su STATE_COMPLETED. Ciò significa che il set di dati è pronto utilizzare nella tua app. Per determinare il valore state del set di dati, consulta Ottenere un del set di dati.

Puoi anche caricare nuovi dati nel set di dati per creare una nuova versione del del set di dati. Per caricare nuovi dati, utilizza la stessa procedura utilizzata per il caricamento dei dati. da Cloud Storage o Carica i dati da un file, e specificare i nuovi dati da caricare.

Se i nuovi dati vengono caricati correttamente:

  • Lo stato della nuova versione del set di dati è impostato su STATE_COMPLETED.

  • La nuova versione diventa "attiva" ed è la versione utilizzata dell'app.

Se si verifica un errore durante il caricamento:

  • Lo stato della nuova versione del set di dati è impostato su uno dei seguenti stati:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • La versione corretta del set di dati precedente rimane "attiva" ed è la versione utilizzata dalla tua app.