Die Erstellung eines Datasets erfolgt in zwei Schritten:
Stellen Sie eine Anfrage zum Erstellen des Datasets.
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.
Vorbereitung
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 Linienzeichenfolgen oder Polygone Quelldateien, die größer als 50 MB sind, fallen in diese Kategorie. Erwägen Sie, Ihre Daten zu vereinfachen. um eine optimale Leistung zu erzielen.
Hier sind einige Best Practices für die Vorbereitung Ihrer Daten:
- Minimieren Sie Feature-Properties. Nur Elementeigenschaften beibehalten, die zum Gestalten von Elementen erforderlich sind Ihre Karte, zum Beispiel "id" und „Kategorie“. Sie können zusätzliche Properties mit einem Feature in einem Client verknüpfen. Anwendung, bei der datengestützte Stile für einen eindeutigen ID-Schlüssel verwendet werden. Siehe zum Beispiel Daten mit datengestützten Stilen in Echtzeit ansehen
- Verwenden Sie nach Möglichkeit einfache Datentypen für Property-Objekte wie Ganzzahlen, um die Kachelgröße zu minimieren und die Kartenleistung zu verbessern.
- Vereinfachen Sie komplexe Geometrien, bevor Sie eine Datei hochladen. Sie können dies in einem Geodaten-Tool Ihrer Wahl, z. B. das Open-Source-Tool Mapshaper.org oder in BigQuery mit ST_Simplify mit komplexen Polygongeometrien.
- Cluster sehr dichte Punkte vor dem Hochladen einer Datei Sie können dies in einem Geodaten-Tool Ihrer Wahl, z. B. das Open-Source-Tool turf.js-Clusterfunktionen oder in BigQuery mit ST_CLUSTERDBSCAN an dichten 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 Koordinatenreferenzsystem enthalten. (CRS) mit Ausnahme von WGS84.
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.
<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
undlong
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 odertype
ist kein String. Die hochgeladene GeoJSON-Datendatei muss als Bestandteil der Definition jedes Feature- und Geometrieobjekts ein Stringfeld mit dem Namentype
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
undy
Ihre Geometriespalten sind, müssen die Einheiten Längen- bzw. Breitengrad sein. Einige öffentliche Datasets verwenden unter den Spaltenüberschriftenx
undy
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 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 vondisplayName
muss für alle Datasets 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 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.
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 Formatgs://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 ZugriffssteuerungVerwenden Sie
fileFormat
, um das Dateiformat der Daten anzugeben: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 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, entwederFILE_FORMAT_GEOJSON
(GeoJSON-Datei),FILE_FORMAT_KML
(KML-Datei) oderFILE_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" }
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.