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 Datenupload können Sie neue Daten in das Dataset hochladen, um eine neue Version des Datasets zu erstellen.

Voraussetzungen

Beim Erstellen eines Datensatzes ist Folgendes zu beachten:

  • Anzeigenamen müssen innerhalb Ihres Google Cloud-Projekts eindeutig sein.
  • Anzeigenamen müssen kleiner als 64 Byte sein. Da diese Zeichen in UTF-8 dargestellt werden, kann in einigen Sprachen jedes Zeichen durch mehrere Bytes dargestellt werden.
  • Beschreibungen müssen kleiner als 1.000 Byte sein.

Beim Hochladen von Daten ist Folgendes zu beachten:

  • Unterstützte Dateitypen sind CSV, GeoJSON und KML.
  • Die maximal zulässige Dateigröße beträgt 350 MB.
  • Die Namen von Attributspalten dürfen nicht mit dem String „?_“ beginnen.
  • Dreidimensionale Geometrien werden nicht unterstützt. Dazu gehören das Suffix „Z“ im WKT-Format und die Höhenkoordinaten im GeoJSON-Format.

Best Practices für die Datenvorbereitung

Wenn Ihre Quelldaten komplex oder groß sind, z. B. dichte Punkte, lange LineStrings oder Polygone (häufige Quelldateien, die größer als 50 MB sind), sollten Sie Ihre Daten vor dem Hochladen vereinfachen, um die beste Leistung in einer visuellen Karte zu erzielen.

Hier sind einige Best Practices für die Vorbereitung Ihrer Daten:

  1. Minimieren Sie Feature-Properties. Behalten Sie nur Elementeigenschaften bei, die zum Gestalten Ihrer Karte erforderlich sind, z. B. „id“ und „category“. Mithilfe von datengestützten Stilen für einen eindeutigen Kennungsschlüssel können Sie einem Element in einer Clientanwendung zusätzliche Attribute verknüpfen. Weitere Informationen
  2. Verwenden Sie nach Möglichkeit einfache Datentypen für Attributobjekte (z. B. Ganzzahlen), um die Kachelgröße zu minimieren und die Kartenleistung zu verbessern.
  3. Vereinfachen Sie komplexe Geometrien, bevor Sie eine Datei hochladen. Dazu können Sie ein Geodatentool Ihrer Wahl verwenden, z. B. das Open-Source-Dienstprogramm Mapshaper.org, oder in BigQuery mit ST_Simplify komplexe Polygongeometrien bearbeiten.
  4. Cluster sehr dichte Punkte vor dem Hochladen einer Datei Sie können dazu ein Geoinformationstool Ihrer Wahl verwenden, z. B. die Open-Source-turf.js-Clusterfunktionen, oder in BigQuery mit ST_CLUSTERDBSCAN für dichte Punktgeometrien.

Weitere Informationen zu Best Practices für Datasets finden Sie unter Daten mit Datasets und BigQuery visualisieren.

Anforderungen für GeoJSON-Dateien

Die Maps Datasets API unterstützt die aktuelle GeoJSON-Spezifikation. Die Maps Datasets API unterstützt auch GeoJSON-Dateien, die einen der folgenden Objekttypen enthalten:

  • Geometrieobjekte. Ein Geometrieobjekt ist eine räumliche Form, die als Einheit aus Punkten, Linien und Polygonen mit optionalen Löchern beschrieben wird.
  • Feature-Objekte. Ein Feature-Objekt enthält eine Geometrie sowie zusätzliche Name/Wert-Paare, deren Bedeutung anwendungsspezifisch ist.
  • Feature-Sammlungen. Eine Feature-Sammlung besteht aus einer Reihe von Feature-Objekten.

Die Maps Datasets API unterstützt keine GeoJSON-Dateien, die Daten in einem anderen Koordinatenreferenzsystem (CRS) als WGS84 enthalten.

Weitere Informationen zu GeoJSON finden Sie unter diesem Link.

Anforderungen für KML-Dateien

Für die Maps Datasets API gelten die folgenden Anforderungen:

  • Alle URLs müssen lokal oder relativ zur Datei selbst sein.
  • Punkt-, Linien- und Polygongeometrien werden unterstützt.
  • Alle Datenattribute werden als Strings betrachtet.
Die folgenden KML-Funktionen werden nicht unterstützt:
  • <styleUrl> oder Symbole, die außerhalb der Datei definiert wurden
  • Netzwerk-Links, z. B. <NetworkLink>
  • Boden-Overlays, z. B. <GroundOverlay>
  • 3D-Geometrien oder höhenbezogene Tags wie <altitudeMode>
  • Kameraspezifikationen wie etwa <LookAt>
  • In der KML-Datei definierte Stile

Anforderungen für CSV-Dateien

Im Folgenden sind die zulässigen Spaltennamen für CSV-Dateien nach ihrer Priorität aufgelistet:

  • latitude, longitude
  • lat, long
  • x, y
  • wkt (Well-Known Text)
  • address, city, state, zip
  • address
  • Eine einzelne Spalte mit allen Adressinformationen, z. B. 1600 Amphitheatre Parkway Mountain View, CA 94043

Die Datei enthält beispielsweise Spalten mit den Namen x, y und wkt. Da x und y eine höhere Priorität haben – wie aus der Reihenfolge der zulässigen Spaltennamen in der Liste oben hervorgeht –, werden die Werte in den Spalten x und y verwendet und die Spalte wkt ignoriert.

Außerdem gilt:

  • Jeder Spaltennamen muss zu einer einzigen Spalte gehören. Das heißt, Sie können keine Spalte namens xy mit x- und y-Koordinatendaten haben. Die x- und y-Koordinaten müssen sich in separaten Spalten befinden.
  • Bei Spaltennamen wird Groß-/Kleinschreibung nicht berücksichtigt.
  • Die Reihenfolge der Spaltennamen spielt keine Rolle. Wenn die CSV-Datei beispielsweise die Spalten lat und long enthält, können sie in beliebiger Reihenfolge verwendet werden.

Fehler beim Hochladen von Daten beheben

Beim Hochladen von Daten in einen Datensatz kann einer der in diesem Abschnitt beschriebenen Fehler auftreten.

GeoJSON-Fehler

Häufiger GeoJSON-Fehler:

  • Das Feld type fehlt oder type ist kein String. Die hochgeladene GeoJSON-Datendatei muss als Bestandteil der Definition jedes Feature- und Geometrieobjekts ein Stringfeld mit dem Namen type enthalten.

KML-Fehler

Häufiger KML-Fehler:

  • Wenn die Datendatei eine der oben aufgeführten nicht unterstützten KML-Features enthält, kann der Datenimport fehlschlagen.

CSV-Fehler

Häufige CSV-Fehler:

  • Bei einigen Zeilen fehlen Werte für eine Geometriespalte. Alle Zeilen in einer CSV-Datei müssen in den Geometriespalten Werte enthalten, die nicht leer sind. Geometriespalten sind:
    • latitude, longitude
    • lat, long
    • x, y
    • wkt
    • address, city, state, zip
    • address
    • Eine einzelne Spalte mit allen Adressinformationen, z. B. 1600 Amphitheatre Parkway Mountain View, CA 94043
  • Wenn x und y Ihre Geometriespalten sind, müssen die Einheiten Längen- bzw. Breitengrad sein. Einige öffentliche Datasets verwenden unter den Spaltenüberschriften x und y andere Koordinatensysteme. Wenn die falschen Einheiten verwendet werden, wird der Datensatz unter Umständen trotzdem erfolgreich importiert. Die Datensatzpunkte können bei den gerenderten Daten aber an unerwarteten Orten auftreten.

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 einen JSON-Text an die Anfrage, mit der das Dataset definiert wird. 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 im Format projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID sowie weitere 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.

Daten aus Cloud Storage hochladen

Zum Hochladen aus Cloud Storage in Ihr Dataset senden Sie eine POST-Anfrage an den datasets-Endpunkt, der 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 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.

  • 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, der auch die ID des Datasets enthält:

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.

  • Die Eigenschaft metadata, die den Pfad zu einer Datei angibt, die den Typ der hochzuladenden Daten angibt, 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 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 das folgende Format:

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

Neue Daten in das Dataset 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. Verwenden Sie zum Hochladen neuer Daten denselben Prozess wie unter Daten aus Cloud Storage hochladen oder Daten aus einer Datei hochladen und geben Sie an, welche neuen Daten hochgeladen werden sollen.

Wenn die neuen Daten erfolgreich hochgeladen wurden:

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

  • Die neue Version wird zur „aktiven“ Version und ist die Version, die von Ihrer Anwendung verwendet wird.

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 die "aktive" Version und ist die Version, die von Ihrer Anwendung verwendet wird.