Utwórz zbiór danych

Tworzenie zbioru danych to proces dwuetapowy:

  1. Prześlij prośbę o utworzenie zbioru danych.

  2. wysłać prośbę o przesłanie danych do zbioru danych;

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

Tworzenie zbioru danych

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

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

Przekaż do żądania treść JSON, która definiuje zbiór danych. Musisz:

  • Określ displayName zbioru danych. Wartość displayName musi być niepowtarzalna we wszystkich zbiorach danych.

  • Ustaw wartość 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 oraz dodatkowe informacje. Używaj identyfikatora zbioru danych podczas wysyłania żą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" 
}

Przesyłanie danych do zbioru danych

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

Operacja przesyłania jest asynchroniczna. Po przesłaniu dane są wczytywane i przetwarzane. Oznacza to, że musisz wysłać żądanie HTTP GET, aby monitorować stan zbioru danych i sprawdzić, kiedy będzie on gotowy do użycia lub czy wystąpiły jakieś błędy. Więcej informacji znajdziesz w artykule Pobieranie stanu przetwarzania danych.

Przesyłanie danych z Cloud Storage

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

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

W treści żądania w formacie JSON:

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

    Użytkownik wysyłający żądanie musi mieć rolę Przeglądający obiekt pamięci lub inną rolę, która obejmuje uprawnienie storage.objects.get. Więcej informacji o zarządzaniu dostępem do Cloud Storage znajdziesz w artykule Omówienie kontroli dostępu.

  • Użyj fileFormat, aby określić format pliku danych: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 postać:

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

Przesyłanie danych 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

Żądanie zawiera:

  • Nagłówek Goog-Upload-Protocol ma wartość multipart.

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

    Zawartość tego pliku ma taki 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 użyto opcji curl -F, aby określić ścieżkę do 2 plików:

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 postać:

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

Pobieranie stanu przetwarzania danych

Operacja przesyłania jest asynchroniczna. Oznacza to, że po wywołaniu interfejsu API w celu przesłania danych do zbioru danych musisz sprawdzić, czy wczytywanie i przetwarzanie danych zakończyło się powodzeniem, czy nie.

Aby określić state zbioru danych, użyj funkcji Pobierz zbiór danych. Na przykład podczas przetwarzania danych wartość state jest ustawiona na STATE_PROCESSING. Gdy zbiór danych będzie gotowy do użycia w aplikacji, wartość state zmieni się na STATE_COMPLETED.

Na przykład wywołaj GET w zbiorze 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 przesłanie się powiodło, state zbioru danych musi wynosić 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
}

Gdy przetwarzanie danych się nie powiedzie, wartość parametru state jest ustawiana na wartość inną niż STATE_COMPLETED, np. STATE_PUBLISHING_FAILED lub dowolny stan kończący się ciągiem znaków _FAILED.

Możesz na przykład przesłać dane do zbioru danych, a następnie wysłać żądanie GET, aby uzyskać szczegółowe informacje o zbiorze danych. Oprócz właściwości state odpowiedź zawiera też pojedynczą właściwość errorMessage z opisem błędu.

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

Pobieranie błędów przetwarzania danych

Gdy przesyłanie i przetwarzanie danych się nie powiedzie, właściwość errorMessage zawiera pojedynczy komunikat opisujący błąd. Jednak pojedynczy komunikat o błędzie nie zawsze zawiera wystarczające informacje, aby zidentyfikować i naprawić problemy.

Aby uzyskać pełne informacje o błędzie, wywołaj interfejs API fetchDatasetErrors. 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 typu Status na wywołanie i obsługuje maksymalnie 500 błędów łącznie:

{
  "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 błędów jest więcej niż 50, czyli więcej niż 1 strona błędów, odpowiedź zawiera token strony w polu nextPageToken. Przekaż tę wartość w parametrze zapytania pageToken w kolejnym wywołaniu, aby uzyskać następną stronę błędów. Gdy pole nextPageToken jest puste, nie ma więcej stron.

Aby na przykład pobrać następną stronę błędów za pomocą tokena z poprzedniej odpowiedzi:

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ę. Aby kontrolować rozmiar strony, użyj parametru zapytania pageSize.

Przesyłanie nowych danych do zbioru danych

Po utworzeniu zbioru danych i przesłaniu początkowych danych stan zbioru danych zostanie ustawiony na STATE_COMPLETED. Oznacza to, że zbiór danych jest gotowy do użycia w aplikacji. Aby określić state zbioru danych, zapoznaj się z artykułem Pobieranie zbioru danych.

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

Jeśli nowe dane zostaną przesłane:

  • Stan nowej wersji zbioru danych zostanie ustawiony na STATE_COMPLETED.

  • Nowa wersja staje się wersją „aktywną” i jest używana przez Twoją aplikację.

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 wersja zbioru danych pozostaje „aktywną” wersją i jest używana przez aplikację.