Ta strona została przetłumaczona przez Cloud Translation API.

Utwórz zbiór danych

Tworzenie zbioru danych to proces dwuetapowy:

Prześlij prośbę o utworzenie zbioru danych.
Prześlij prośbę o przesłanie danych do zbioru danych.

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

Tworzenie zbioru danych

Aby utworzyć zbiór danych, wyślij żądanie POST do punktu końcowego datasets:

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

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

Podaj displayName zbioru danych. Wartość właściwości displayName musi być niepowtarzalna we wszystkich zbiorach danych.
Ustaw usage na USAGE_DATA_DRIVEN_STYLING.

Uwaga: USAGE_DATA_DRIVEN_STYLING to jedyna wartość obsługiwana w przypadku atrybutu usage.

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_IDoraz dodatkowe informacje. Używaj identyfikatora zbioru danych, gdy wysyłasz żądania jego aktualizacji lub modyfikacji.

{
  "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 danych są one przetwarzane i przechowywane. Oznacza to, że musisz wysłać żądanie HTTP GET, aby monitorować stan zbioru danych i określić, kiedy będzie on gotowy do użycia lub czy wystąpiły jakieś błędy. Więcej informacji znajdziesz w artykule o przetwarzaniu danych.

Przesyłanie danych z Cloud Storage

Przesyłasz dane z Cloud Storage do zbioru danych, wysyłając żądanie POST do punktu końcowego datasets, który zawiera również 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ę do zasobu zawierającego dane w Cloud Storage. Ścieżka ma format gs://GCS_BUCKET/FILE.

Użytkownik przesyłający żądanie musi mieć rolę Storage Object Viewer 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 parametru 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óry zawiera też 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 ma wartość 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 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 ścieżka do 2 plików jest określona za pomocą opcji 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 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 należy przeprowadzić jego odpytywanie, aby określić, czy pobieranie i przetwarzanie danych się powiodło.

Aby określić state zbioru danych, użyj polecenia Pobierz zbiór danych. Podczas przetwarzania danych wartość parametru state jest ustawiona na STATE_PROCESSING. Gdy zbiór danych będzie gotowy do użycia w aplikacji, wartość state zostanie ustawiona na STATE_COMPLETED.

Na przykład możesz wykonać wywołanie 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 przesłać dane, state zbioru danych musi być 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, parametr state zostanie ustawiony 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 potem wysłać żądanie GET, aby uzyskać szczegóły zbioru danych. Oprócz właściwości state odpowiedź zawiera też jedną 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 przetwarzanie i przekształcanie danych się nie powiedzie, właściwość errorMessage zawiera pojedynczy komunikat opisujący błąd. Jednak pojedynczy komunikat o błędzie niekoniecznie zawiera wystarczające informacje do zidentyfikowania i naprawienia problemów.

Aby uzyskać pełne informacje o błędzie, wywołaj interfejs API fetchDatasetErrors. Ten interfejs API zwraca wszystkie błędy przetwarzania danych związane z danym 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:

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

Aby na przykład uzyskać 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 pomyślnym przesłaniu początkowych danych stan zbioru danych jest ustawiany 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ć nowe dane do zbioru danych, aby utworzyć jego nową wersję. Aby przesłać nowe dane, użyj tego samego procesu, który został użyty do przesł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 pomyślnie:

Stan nowej wersji zbioru danych to STATE_COMPLETED.
Nowa wersja staje się „aktywna” i jest używana przez 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, która przeszła testy, pozostaje „aktywną” wersją i jest używana przez aplikację.