Die Erstellung eines Datasets erfolgt in zwei Schritten:
Stellen Sie eine Anfrage zum Erstellen des Datensatzes.
Stellen Sie eine Anfrage zum Hochladen von Daten in das Dataset.
Nach dem ersten Datenupload können Sie neue Daten in das Dataset hochladen, um eine neue Version des Datasets zu erstellen.
Dataset erstellen
Erstellen Sie ein Dataset, indem Sie eine POST
-Anfrage an den datasets-Endpunkt senden:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Übergeben Sie der Anfrage, die das Dataset definiert, einen JSON-Text. Die folgenden Anforderungen müssen erfüllt sein:
Geben Sie die
displayName
des Datensatzes an. Der Wert vondisplayName
muss für alle Datensätze eindeutig sein.Setzen Sie
usage
aufUSAGE_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 Datensatzes im Format projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
sowie zusätzliche Informationen. Verwenden Sie die Dataset-ID, wenn Sie Anfragen zum Aktualisieren oder Ändern des Datasets stellen.
{ "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 einer lokalen Datei in das Dataset hoch.
Der Uploadvorgang ist asynchron. Nachdem Sie die Daten hochgeladen haben, werden sie aufgenommen und verarbeitet. Das bedeutet, dass Sie eine HTTP-GET-Anfrage senden müssen, um den Status des Datasets zu überwachen und festzustellen, wann das Dataset einsatzbereit ist oder ob Fehler aufgetreten sind. Weitere Informationen finden Sie unter Datenverarbeitungsstatus abrufen.
Daten aus Cloud Storage hochladen
Sie laden Daten von Cloud Storage in Ihr Dataset hoch, indem Sie eine POST
-Anfrage an den Endpunkt datasets senden, die auch die ID des Datasets enthält:
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 in Cloud Storage anzugeben, die die Daten enthält. Dieser Pfad hat das Formatgs://GCS_BUCKET/FILE
.Der Nutzer, der die Anfrage stellt, benötigt die Rolle Storage Object Viewer oder eine andere Rolle mit der Berechtigung
storage.objects.get
. Weitere Informationen zum Verwalten des Zugriffs auf Cloud Storage finden Sie unter Übersicht über die Zugriffssteuerung.Geben Sie mit
fileFormat
das Dateiformat der Daten an:FILE_FORMAT_GEOJSON
(GeoJSON-Datei),FILE_FORMAT_KML
(KML-Datei) oderFILE_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 folgendes 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 Endpunkt datasets, die auch die ID des Datensatzes enthält:
https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
Die Anfrage enthält:
Der Header „
Goog-Upload-Protocol
“ ist auf „multipart
“ festgelegt.Die Eigenschaft
metadata
, die den Pfad zu einer Datei angibt, die den Typ der hochzuladenden Daten angibt, entwederFILE_FORMAT_GEOJSON
(GeoJSON-Datei),FILE_FORMAT_KML
(KML-Datei) oderFILE_FORMAT_CSV
(CSV-Datei).Der Inhalt der Datei hat folgendes Format:
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
Die Eigenschaft
rawdata
, die den Pfad zur GeoJSON-, KML- oder CSV-Datei mit den hochzuladenden Daten angibt.
In der folgenden Anfrage wird mit der Option curl -F
der Pfad zu den beiden Dateien angegeben:
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 folgendes Format:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Datenverarbeitungsstatus abrufen
Der Uploadvorgang ist asynchron. Das bedeutet, dass Sie nach dem API-Aufruf zum Hochladen der Daten in das Dataset das Dataset abfragen müssen, um festzustellen, ob die Datenaufnahme und -verarbeitung erfolgreich war oder fehlgeschlagen ist.
Mit Dataset abrufen können Sie die state
des Datasets ermitteln. Während die Daten verarbeitet werden, wird beispielsweise state
auf STATE_PROCESSING
gesetzt. Wenn der Datensatz in Ihrer App verwendet werden kann, wird 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 ist die state
des Datensatzes 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 für state
ein anderer Wert als STATE_COMPLETED
festgelegt, z. B. STATE_PUBLISHING_FAILED
oder ein Status, der mit _FAILED
endet.
Sie laden beispielsweise Daten in ein Dataset hoch und senden dann eine GET-Anfrage, um die Dataset-Details abzurufen. Neben der state
-Property enthält die Antwort auch eine einzelne errorMessage
-Property mit einer Beschreibung des Fehlers.
{ "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 fehlschlägt, enthält die Property errorMessage
eine einzelne Meldung, die den Fehler beschreibt. Eine einzelne Fehlermeldung enthält jedoch nicht unbedingt ausreichend Informationen, um die Probleme zu identifizieren und zu beheben.
Rufen Sie die fetchDatasetErrors
API auf, um vollständige Fehlerinformationen zu erhalten. 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 vom Typ Status
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)" }, ... ] }
Wenn es mehr als 50 Fehler gibt, d. h. mehr als eine Seite mit Fehlern, enthält die Antwort ein Seitentoken im Feld nextPageToken
.
Geben Sie diesen Wert im Abfrageparameter pageToken
eines nachfolgenden Aufrufs an, um die nächste Seite mit Fehlern abzurufen. Wenn nextPageToken
leer ist, gibt es keine weiteren Seiten.
So rufen Sie beispielsweise mit dem Token aus der vorherigen Antwort die nächste Fehlerseite ab:
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. Mit dem Abfrageparameter pageSize
können Sie die Seitengröße steuern.
Neue Daten in den Datensatz hochladen
Nachdem Sie das Dataset erstellt und die ursprünglichen Daten erfolgreich hochgeladen haben, wird der Status des Datasets auf STATE_COMPLETED
gesetzt. Das bedeutet, dass das Dataset sofort in Ihrer Anwendung verwendet werden kann. Informationen zum Ermitteln des state
des Datasets finden Sie unter Dataset abrufen.
Sie können auch neue Daten in das Dataset hochladen, um eine neue Version des Datasets zu erstellen. Wenn Sie neue Daten hochladen möchten, gehen Sie wie beim Hochladen von Daten aus Cloud Storage oder Hochladen von Daten aus einer Datei vor und geben Sie die neuen Daten an, die hochgeladen werden sollen.
Wenn die neuen Daten erfolgreich hochgeladen wurden:
Der Status der neuen Version des Datensatzes ist auf
STATE_COMPLETED
festgelegt.Die neue Version wird zur „aktiven“ Version und ist die Version, die von Ihrer Anwendung verwendet wird.
Wenn beim Hochladen 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 Datensatzes bleibt als „aktive“ Version erhalten und wird von Ihrer App verwendet.