Tworzenie zbioru danych

Tworzenie zbioru danych to proces dwuetapowy:

1. Wyślij żądanie utworzenia zbioru danych.

2. Wyślij żądanie przesłania danych do zbioru danych.

Wymagania wstępne

Podczas tworzenia zbioru danych:

• Wyświetlane nazwy muszą być unikalne w obrębie projektu Google Cloud.
• Wyświetlane nazwy muszą mieć mniej niż 64 bajty (ponieważ te znaki są reprezentowane w formacie UTF-8, dlatego w niektórych językach każdy znak może być reprezentowany przez wiele bajtów).
• Opisy muszą być mniejsze niż 1000 bajtów.

Podczas przesyłania danych:

• Obsługiwane typy plików to CSV, GeoJSON i KML.
• Maksymalny obsługiwany rozmiar pliku to 350 MB.
• Nazwy kolumn atrybutów nie mogą zaczynać się od „?_”.
• Trójwymiarowe geometrie nie są obsługiwane. Obejmuje to sufiks „Z” w formacie WKT i współrzędne wysokości w formacie GeoJSON.

Uwaga: w zależności od rozmiaru pliku danych przesyłanie może potrwać kilka minut lub nawet godzin. Jeśli podczas przesyłania wystąpi błąd, pojawi się komunikat o błędzie. Nie próbuj usuwać zbioru danych, dopóki nie zwróci on odpowiedzi z operacji przesyłania.

Wskazówka: jeśli plik danych jest duży i zawiera wiele atrybutów, których nie potrzebujesz do określania stylu, a chcesz zoptymalizować wydajność renderowania, edytuj plik, aby usunąć niepotrzebne atrybuty. Zmniejszenie liczby atrybutów zmniejsza rozmiar kafelków mapy, a tym samym poprawia wydajność renderowania.

Wymagania GeoJSON

Interfejs Maps Datasets API obsługuje bieżącą specyfikację GeoJSON. Interfejs Maps Datasets API obsługuje też pliki GeoJSON, które zawierają dowolny z tych typów obiektów:

• Obiekty geometryczne. Obiekt geometryczny to kształt przestrzenny określany jako połączenie punktów, linii i wielokątów z opcjonalnymi otworami.
• Obiekty funkcji. Obiekt funkcji zawiera geometrię i dodatkowe pary nazwa/wartość, których znaczenie jest charakterystyczne dla aplikacji.
• Kolekcje funkcji. Kolekcja cech to zbiór obiektów cech.

Interfejs Maps Datasets API nie obsługuje plików GeoJSON, które zawierają dane w układzie współrzędnych (CRS) innym niż WGS84.

Więcej informacji o GeoJSON znajdziesz w artykule Zgodność z RFC 7946.

Wymagania dotyczące plików KML

Interfejs Maps Datasets API ma następujące wymagania:

• Wszystkie adresy URL muszą być lokalne (lub względne) w stosunku do samego pliku.
• Geometria punktów, linii i wielokątów jest obsługiwana.
• Wszystkie atrybuty danych są traktowane jako ciągi znaków.

Te funkcje KML nie są obsługiwane:

• Ikony lub <styleUrl> zdefiniowane poza plikiem.
• Linki sieciowe, takie jak <NetworkLink>
• Nakładki na powierzchni, np. <GroundOverlay>
• Geometrie 3D lub wszelkie tagi związane z wysokością, np. <altitudeMode>
• Specyfikacje aparatu, takie jak <LookAt>
• Style zdefiniowane w pliku KML.

Wymagania dotyczące pliku CSV

W przypadku plików CSV obsługiwane nazwy kolumn są wymienione poniżej w kolejności według priorytetu:

• latitude, longitude
• lat, long
• x, y
• wkt (Znany tekst)
• address, city, state, zip
• address
• jedna kolumna zawierająca wszystkie informacje adresowe, np. 1600 Amphitheatre Parkway Mountain View, CA 94043

Twój plik zawiera np. kolumny o nazwach x, y i wkt. Ponieważ x i y mają wyższy priorytet (zgodnie z kolejnością obsługiwanych nazw kolumn z listy powyżej), wartości w kolumnach x i y są używane, a kolumna wkt jest ignorowana.

Ponadto:

• Każda nazwa kolumny musi należeć do jednej kolumny. Oznacza to, że kolumna o nazwie xy nie może zawierać danych współrzędnych x i Y. Współrzędne x i y muszą znajdować się w osobnych kolumnach.
• W nazwach kolumn nie jest rozróżniana wielkość liter.
• Kolejność nazw kolumn nie ma znaczenia. Jeśli na przykład plik CSV zawiera kolumny lat i long, mogą one występować w dowolnej kolejności.

Obsługa błędów przesyłania danych

Podczas przesyłania danych do zbioru danych może wystąpić jeden z częstych błędów opisanych w tej sekcji.

Błędy GeoJSON

Typowe błędy GeoJSON:

• Brak pola type lub type nie jest ciągiem znaków. Przesłany plik danych GeoJSON musi zawierać pole ciągu znaków o nazwie type w każdej definicji obiektu Feature i Geometry.

Błędy KML

Typowe błędy w formacie KML to:

• Plik danych nie może zawierać żadnych nieobsługiwanych funkcji KML wymienionych powyżej. W przeciwnym razie import danych może się nie udać.

Błędy pliku CSV

Typowe błędy w pliku CSV:

• W niektórych wierszach brakuje wartości w kolumnie geometrii. Wszystkie wiersze w pliku CSV muszą zawierać niepuste wartości kolumn geometrycznych. Kolumny geometryczne:
  • latitude, longitude
  • lat, long
  • x, y
  • wkt
  • address, city, state, zip
  • address
  • jedna kolumna zawierająca wszystkie informacje adresowe, np. 1600 Amphitheatre Parkway Mountain View, CA 94043
  Uwaga: ten błąd jest często opisywany przez komunikat w formie „Nie udało się przekonwertować elementu ' ” na typ zmiennoprzecinkowy lub „Nie udało się przeanalizować danych wejściowych na potrzeby lokalizacji geograficznej.: Brak wartości geograficznej”.
• Jeśli kolumny geometryczne to x i y, sprawdź, czy podane jednostki to długość i szerokość geograficzna. Niektóre publiczne zbiory danych używają różnych układów współrzędnych pod nagłówkami x i y. Jeśli zostaną użyte nieprawidłowe jednostki, zbiór danych może zostać zaimportowany, ale wyrenderowane dane mogą wskazywać punkty zbioru danych w nieoczekiwanych lokalizacjach.

wysyłania żądania utworzenia zbioru danych;

Utwórz zbiór danych, wysyłając żądanie POST do punktu końcowego zbiorów danych:

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

Przekaż do żądania treść JSON określającą zbiór danych. Musisz:

• Określ displayName zbioru danych. Wartość displayName musi być unikalna dla wszystkich zbiorów danych.

• Ustaw wartość usage na USAGE_DATA_DRIVEN_STYLING.

  Uwaga: obecnie jedyną obsługiwaną wartością w przypadku usage jest USAGE_DATA_DRIVEN_STYLING.

Na przykład:

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

Odpowiedź zawiera identyfikator zbioru danych w postaci projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID wraz z dodatkowymi informacjami. Używaj identyfikatora zbioru danych przy wysyłaniu żądań aktualizacji lub modyfikacji zbioru danych.

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

Wyślij żądanie przesłania danych do zbioru danych

Gdy utworzysz zbiór danych, prześlij do niego dane z Google Cloud Storage lub z pliku lokalnego.

Uwaga: dane do zbioru danych możesz przesłać tylko raz. Oznacza to, że po uruchomieniu żądania przesłania danych z Cloud Storage lub z pliku lokalnego nie możesz ponownie przesłać danych do tego samego zbioru danych. Jeśli podczas przesyłania wystąpi błąd, musisz ponownie utworzyć zbiór danych i spróbować jeszcze raz.

Prześlij dane z Cloud Storage

Aby przesyłać dane z Cloud Storage do zbioru danych, wyślij do punktu końcowego datasets żądanie POST, które zawiera też identyfikator zbioru danych:

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

W treści żądania JSON:

• Użyj inputUri, aby określić ścieżkę pliku do zasobu zawierającego dane w Cloud Storage. Ma ona format gs://GCS_BUCKET/FILE.

  Użytkownik przesyłający żądanie musi mieć przypisaną rolę Przeglądający obiekty Cloud Storage lub dowolną inną rolę zawierającą uprawnienie storage.objects.get. Więcej informacji o zarządzaniu dostępem do Cloud Storage znajdziesz w omówieniu kontroli dostępu.

• Użyj właściwości fileFormat, aby określić format pliku danych w jednym z tych sposobów: FILE_FORMAT_GEOJSON (plik GeoJson), FILE_FORMAT_KML (plik KML) lub FILE_FORMAT_CSV (plik CSV).

Na przykład:

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

Odpowiedź ma taki format:

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

Prześlij dane z pliku

Aby przesłać dane z pliku, wyślij żądanie HTTP POST do punktu końcowego datasets, które zawiera też identyfikator zbioru danych:

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

Uwaga: URL żądania przesłania danych z pliku różni się od adresu URL do przesyłania danych z Google Cloud Storage.

Prośba zawiera:

• Nagłówek Goog-Upload-Protocol jest ustawiony na multipart.

• Właściwość metadata określająca ścieżkę do pliku, która określa typ danych do przesłania: FILE_FORMAT_GEOJSON (plik GeoJSON), FILE_FORMAT_KML (plik KML) lub FILE_FORMAT_CSV (plik CSV).

  Zawartość tego pliku ma następujący format:

  {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

• Właściwość rawdata określająca ścieżkę do pliku GeoJSON, KML lub CSV zawierającego dane do przesłania.

W tym żądaniu do określenia ścieżki do 2 plików używana jest opcja curl -F:

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

Odpowiedź ma taki format:

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