Diese Seite wurde von der Cloud Translation API übersetzt.

Dataset erstellen

Das Erstellen eines Datensatzes erfolgt in zwei Schritten:

Stellen Sie eine Anfrage zum Erstellen des Datensatzes.
Stellen Sie eine Anfrage, um Daten in das Dataset hochzuladen.

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

Dataset erstellen

Senden Sie eine POST-Anfrage an den Endpunkt datasets, um ein Dataset zu erstellen:

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 von displayName muss für alle Datensätze eindeutig sein.
Setzen Sie usage auf USAGE_DATA_DRIVEN_STYLING.

Hinweis: USAGE_DATA_DRIVEN_STYLING ist der einzige für usage unterstützte Wert.

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 den Datensatz hochladen

Nachdem Sie den Datensatz erstellt haben, laden Sie die Daten aus Google Cloud Storage oder aus einer lokalen Datei in den Datensatz hoch.

Der Uploadvorgang ist asynchron. Nachdem Sie die Daten hochgeladen haben, werden sie aufgenommen und verarbeitet. Sie müssen also eine HTTP-GET-Anfrage stellen, um den Status des Datensatzes zu überwachen und festzustellen, wann er einsatzbereit ist oder ob Fehler aufgetreten sind. Weitere Informationen finden Sie unter Status der Datenverarbeitung 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 anzugeben, die die Daten in Cloud Storage enthält. Dieser Pfad hat das Format gs://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) 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 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 gesetzt.
Die Eigenschaft metadata gibt den Pfad zu einer Datei an, in der der Typ der hochzuladenden Daten angegeben ist: FILE_FORMAT_GEOJSON (GeoJSON-Datei), FILE_FORMAT_KML (KML-Datei) oder FILE_FORMAT_CSV (CSV-Datei).

Der Inhalt der Datei hat folgendes Format:
```
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
```
Das Attribut rawdata gibt den Pfad zur GeoJSON-, KML- oder CSV-Datei an, die die hochzuladenden Daten enthält.

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

Status der Datenverarbeitung abrufen

Der Uploadvorgang ist asynchron. Das bedeutet, dass Sie nach dem API-Aufruf zum Hochladen der Daten in den Datensatz den Datensatz 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, ist state beispielsweise auf STATE_PROCESSING festgelegt. 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 state auf einen anderen Wert als STATE_COMPLETED gesetzt, z. B. STATE_PUBLISHING_FAILED oder einen Status, der auf den String _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 zurück, die mit einem Datensatz verknüpft sind:

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, also mehr als eine Seite mit Fehlern, enthält die Antwort im Feld nextPageToken ein Seitentoken. 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 Seite mit Fehlern 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"

Standardmäßig enthält die Antwort maximal 50 Fehler pro Seite. Verwenden Sie den Abfrageparameter pageSize, um die Seitengröße festzulegen.

Neue Daten in den Datensatz hochladen

Nachdem Sie das Dataset erstellt und die ersten Daten hochgeladen haben, wird der Status des Datasets auf STATE_COMPLETED gesetzt. Das bedeutet, dass das Dataset in Ihrer App verwendet werden kann. Wie Sie die state des Datasets ermitteln, erfahren Sie unter Dataset abrufen.

Sie können auch neue Daten in das Dataset hochladen, um eine neue Version davon 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 App verwendet wird.

Wenn beim Hochladen ein Fehler auftritt:

Der Status der neuen Datasetversion wird auf einen der folgenden Status gesetzt:
- 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.