Utwórz zbiór danych

Tworzenie zbioru danych przebiega dwuetapowo:

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

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

Po pierwszym przesłaniu danych możesz przesłać do zbioru danych nowe dane, aby utworzyć nową wersję zbioru danych.

Tworzenie zbioru danych

Utwórz zbiór danych, wysyłając żądanie POST do Punkt końcowy datasets:

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

Przekaż treści JSON. do żądania definiującego zbiór danych. Musisz:

  • Podaj displayName zbioru danych. Wartość pola displayName musi być być unikalny dla wszystkich zbiorów danych.

  • Ustaw usage na 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 formacie projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID wraz z dodatkowymi informacjami. Używaj identyfikatora zbioru danych przy wysyłaniu żądań do aktualizować lub modyfikować zbiór 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" 
}

Przesyłanie danych do zbioru danych

Po utworzeniu zbioru danych prześlij dane z Google Cloud Storage lub z pliku lokalnego do zbioru danych.

Operacja przesyłania jest asynchroniczna. Po przesłaniu danych zostaną one są przetwarzane i przetwarzane. Oznacza to, że musisz wysłać żądanie HTTP GET, aby monitorować stan zbioru danych, co pozwoli określić, czy zbiór danych jest gotowy do użycia wystąpiły błędy. Więcej informacji znajdziesz w artykule Przetwarzanie danych stanu.

Prześlij dane z Cloud Storage

Aby przesłać dane z Cloud Storage do zbioru danych, wysyłaj żądanie POST do Punkt końcowy datasets, który również zawiera 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. Ta ścieżka ma format gs://GCS_BUCKET/FILE

    Użytkownik wysyłający żądanie wymaga obiektu pamięci masowej Wyświetlający lub inną rolę, która obejmuje uprawnienie storage.objects.get. Dla: więcej informacji o zarządzaniu dostępem do Cloud Storage znajdziesz w artykule Omówienie kontroli dostępu

  • Użyj właściwości fileFormat, aby określić format pliku danych na jeden 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 Punkt końcowy datasets, który również zawiera identyfikator zbioru danych:

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

Prośba zawiera:

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

  • Właściwość metadata określająca ścieżkę do pliku, który 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ący dane do przesłania.

To żądanie używa opcji curl -F do określenia ścieżki do obu źródeł pliki:

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

Pobranie stanu przetwarzania danych

Operacja przesyłania jest asynchroniczna. Oznacza to, że po wywołaniu interfejsu API w celu przesłania dane zwrócone do zbioru danych musisz następnie wykonać sondowanie, aby określić, informacje o tym, czy pozyskiwanie i przetwarzanie danych zakończyło się sukcesem czy niepowodzeniem.

Aby określić state użyj funkcji Pobierz zbiór danych. Na przykład gdy dane są przetwarzane przetworzono, state ma wartość STATE_PROCESSING. Gdy zbiór danych będzie gotowy którego chcesz użyć w aplikacji, uprawnienie state ma wartość STATE_COMPLETED.

Na przykład wywołaj metodę GET zbioru danych:

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"

Aby przesyłanie przebiegło pomyślnie, state zbioru danych ma wartość 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
}

Jeśli przetwarzanie danych się nie uda, state ma ustawioną wartość inną niż STATE_COMPLETED, na przykład STATE_PUBLISHING_FAILED lub dowolny status kończący się znakiem ciąg _FAILED.

Załóżmy np., że przesyłasz dane do zbioru danych, a następnie wykonujesz metodę GET żądania pobrania szczegółów zbioru danych. Wraz z właściwością state para klucz-wartość odpowiedź zawiera też 1 właściwość errorMessage z opisem .

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

Błędy przetwarzania danych

Jeśli pozyskiwanie i przetwarzanie danych się nie uda, właściwość errorMessage zawiera komponent pojedynczy komunikat z opisem błędu. Jednak pojedynczy komunikat o błędzie muszą zawierać informacje wystarczające do identyfikacji i rozwiązania problemu.

Aby uzyskać pełne informacje o błędzie, wywołaj metodę fetchDatasetErrors API. Ten interfejs API zwraca wszystkie błędy przetwarzania danych powiązane ze zbiorem danych:

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"

Odpowiedź zawiera tablicę errors. Ta tablica zawiera maksymalnie 50 błędów: wpisz Status na połączenie i obsługuje łącznie do 500 błędów:

{
  "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)"
    },
    ...
  ]
}

Jeśli wystąpiło więcej niż 50 błędów, czyli więcej niż jedna strona , to odpowiedź będzie zawierać w polu nextPageToken token strony. Przekaż tę wartość w parametrze zapytania pageToken kolejnego wywołania, aby uzyskać na kolejnej stronie błędów. Jeśli pole nextPageToken jest puste, nie ma więcej stron.

Aby na przykład pobrać następną stronę błędów przy użyciu tokena z poprzedniej odpowiedź:

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"

Domyślnie odpowiedź zawiera maksymalnie 50 błędów na stronę. Używaj parametru zapytania pageSize, aby kontrolować rozmiar strony.

Prześlij nowe dane do zbioru danych

Gdy utworzysz zbiór danych i prześlesz dane początkowe, stan zbioru danych jest ustawione na STATE_COMPLETED. Oznacza to, że zbiór danych jest gotowy do używanych w Twojej aplikacji. Aby określić state zbioru danych, zapoznaj się z informacjami o pobieraniu .

Możesz też przesłać nowe dane do zbioru danych, aby utworzyć nową wersję w gromadzeniu danych. Aby przesłać nowe dane, wykonaj te same czynności co w przypadku przesyłania danych z Cloud Storage lub Prześlij dane z pliku, i wskaż nowe dane do przesłania.

Jeśli uda się przesłać nowe dane:

  • Stan nowej wersji zbioru danych jest ustawiony na STATE_COMPLETED.

  • Nowa wersja stanie się „aktywna”. i jest wersją używaną przez .

Jeśli podczas przesyłania wystąpi błąd:

  • Stan nowej wersji zbioru danych jest ustawiony na jeden z tych stanów:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED
  • Poprzednia udana wersja zbioru danych pozostaje „aktywna” i jest wersję używaną przez aplikację.