Dataset erstellen

Die Erstellung eines Datasets erfolgt in zwei Schritten:

  1. Stellen Sie eine Anfrage zum Erstellen des Datasets.

  2. Stellen Sie eine Anfrage zum Hochladen von Daten in das Dataset.

Nach dem ersten Daten-Upload können Sie neue Daten in das Dataset hochladen, um eine neue Version des Datasets.

Dataset erstellen

Erstellen Sie ein Dataset, indem Sie eine POST-Anfrage an den datasets-Endpunkt ein:

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

Übergeben Sie einen JSON-Text. mit der Anfrage zur Definition des Datasets. Die folgenden Anforderungen müssen erfüllt sein:

  • Geben Sie den displayName des Datasets an. Der Wert von displayName muss für alle Datasets eindeutig sein.

  • Setzen Sie usage auf USAGE_DATA_DRIVEN_STYLING.

Beispiel:

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"

Die Antwort enthält die ID des Datasets in der Form projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID sowie weitere Informationen. Verwenden Sie die Dataset-ID bei Anfragen an Aktualisieren oder Ändern des Datasets.

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

Daten in das Dataset hochladen

Nachdem Sie das Dataset erstellt haben, laden Sie die Daten aus Google Cloud Storage oder aus einer lokalen Datei in das Dataset.

Der Uploadvorgang ist asynchron. Nachdem Sie die Daten hochgeladen haben, aufgenommen und verarbeitet werden. Das bedeutet, dass Sie eine HTTP-GET-Anfrage senden müssen, um Status des Datasets, um zu bestimmen, wann das Dataset einsatzbereit ist oder dass es Fehler gab. Weitere Informationen finden Sie unter Datenverarbeitung abrufen. Bundesstaat.

Daten aus Cloud Storage hochladen

Zum Hochladen aus Cloud Storage in Ihr Dataset senden Sie eine POST-Anfrage an den datasets-Endpunkt hinzufügen, enthält die ID des Datasets:

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

Im JSON-Anfragetext:

  • Verwenden Sie inputUri, um den Dateipfad zur Ressource mit den Daten anzugeben in Cloud Storage. Dieser Pfad hat das Format gs://GCS_BUCKET/FILE

    Der Nutzer, der die Anfrage stellt, benötigt das Speicherobjekt Zuschauer oder jede andere Rolle mit der Berechtigung storage.objects.get. Für Weitere Informationen zum Verwalten des Zugriffs auf Cloud Storage finden Sie unter Übersicht über die Zugriffssteuerung

  • Verwenden Sie fileFormat, um das Dateiformat der Daten anzugeben: FILE_FORMAT_GEOJSON (GeoJson-Datei), FILE_FORMAT_KML (KML-Datei) oder FILE_FORMAT_CSV (CSV-Datei).

Beispiel:

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"

Die Antwort hat das folgende Format:

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

Daten aus einer Datei hochladen

Wenn Sie Daten aus einer Datei hochladen möchten, senden Sie eine HTTP-POST-Anfrage an den datasets-Endpunkt hinzufügen, enthält die ID des Datasets:

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

Die Anfrage enthält Folgendes:

  • Der Header „Goog-Upload-Protocol“ ist auf „multipart“ festgelegt.

  • Das Attribut metadata, das den Pfad zu einer Datei angibt, die den Typ der hochzuladenden Daten, entweder FILE_FORMAT_GEOJSON (GeoJSON-Datei), FILE_FORMAT_KML (KML-Datei) oder FILE_FORMAT_CSV (CSV-Datei).

    Der Inhalt dieser Datei hat folgendes Format:

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
  • Die Eigenschaft rawdata, die den Pfad zur GeoJSON-, KML- oder CSV-Datei angibt das die hochzuladenden Daten enthält.

In der folgenden Anfrage wird mit der Option curl -F der Pfad zu den beiden angegeben. Dateien:

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"

Die Antwort hat das folgende Format:

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

Datenverarbeitungsstatus abrufen

Der Uploadvorgang ist asynchron. Nach dem API-Aufruf zum Hochladen die Daten an das Dataset zurückgibt, müssen Sie das Dataset dann abfragen, um ob Datenaufnahme und -verarbeitung erfolgreich waren oder fehlgeschlagen sind.

Um den state des verwenden Sie Dataset abrufen. Während die Daten beispielsweise verarbeitet wurde, ist state auf STATE_PROCESSING gesetzt. Wenn das Dataset bereit ist in Ihrer App verwenden möchten, ist state auf STATE_COMPLETED gesetzt.

Führen Sie beispielsweise einen GET-Aufruf für das Dataset aus:

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"

Bei einem erfolgreichen Upload lautet der state des Datasets 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
}

Wenn die Datenverarbeitung fehlschlägt, wird state auf einen anderen Wert als STATE_COMPLETED, z. B. STATE_PUBLISHING_FAILED oder ein Status mit den Endziffern String _FAILED.

Beispiel: Sie laden Daten in ein Dataset hoch und führen dann eine GET-Anfrage aus. -Anfrage zum Abrufen der Dataset-Details. Zusammen mit der Eigenschaft state enthält das Attribut Die Antwort enthält außerdem eine einzelne errorMessage-Eigenschaft mit einer Beschreibung Fehler.

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

Fehler bei der Datenverarbeitung abrufen

Wenn die Datenaufnahme und -verarbeitung fehlschlagen, enthält das Attribut errorMessage einen eine Nachricht, die den Fehler beschreibt. Eine einzelne Fehlermeldung nicht unbedingt genügend Informationen liefern, um die Probleme zu identifizieren und zu beheben.

Um vollständige Fehlerinformationen zu erhalten, rufen Sie die Methode fetchDatasetErrors der API erstellen. Diese API gibt alle Datenverarbeitungsfehler im Zusammenhang mit einem Dataset zurück:

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"

Die Antwort enthält das Array errors. Dieses Array enthält bis zu 50 Fehler Geben Sie Status ein pro Aufruf und unterstützt insgesamt bis zu 500 Fehler:

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

Bei mehr als 50 Fehlern, d. h. mehr als eine Seite von Fehler enthält, enthält die Antwort ein Seitentoken im Feld nextPageToken. Übergeben Sie diesen Wert im pageToken-Abfrageparameter eines nachfolgenden Aufrufs, um zur nächsten Seite mit Fehlern. Wenn nextPageToken leer ist, sind keine weiteren Seiten vorhanden.

Um beispielsweise die nächste Fehlerseite mit dem Token aus der vorherigen Antwort:

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"

Die Antwort enthält standardmäßig maximal 50 Fehler pro Seite. Verwenden Sie pageSize, um die Seitengröße zu steuern.

Neue Daten in das Dataset hochladen

Nachdem Sie das Dataset erstellt und die ursprünglichen Daten erfolgreich hochgeladen haben, des Datasets auf STATE_COMPLETED festgelegt ist. Das bedeutet, dass das Dataset in Ihrer App nutzen können. Informationen zum Ermitteln des state-Werts des Datasets finden Sie unter Get a Dataset.

Sie können auch neue Daten in das Dataset hochladen, um eine neue Version des Dataset. Wenn Sie neue Daten hochladen möchten, gehen Sie genauso vor wie unter Daten hochladen aus Cloud Storage oder Daten aus einer Datei hochladen, und die neuen hochzuladenden Daten angeben.

Wenn die neuen Daten erfolgreich hochgeladen wurden:

  • Der Status der neuen Version des Datasets ist auf STATE_COMPLETED festgelegt.

  • Die neue Version wird zum „aktiven“ Version und ist die Version, die von Ihrem

Wenn beim Upload ein Fehler auftritt:

  • Die neue Dataset-Version hat einen der folgenden Status:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED
  • Die vorherige erfolgreiche Version des Datasets bleibt als „aktiv“ Version und ist die von Ihrer App verwendete Version.