Veri kümesi oluşturma

Veri kümesi oluşturma iki adımlı bir işlemdir:

  1. Veri kümesini oluşturma isteğinde bulunun.

  2. Veri kümesine veri yükleme isteğinde bulunun.

İlk veri yükleme işleminden sonra, veri kümesinin yeni bir sürümünü oluşturmak için veri kümesine yeni veriler yükleyebilirsiniz.

Veri kümesini oluşturma

datasets uç noktasına bir POST isteği göndererek veri kümesi oluşturun:

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

Veri kümesini tanımlayan isteğe bir JSON gövdesi gönderin. Bu politika uyarınca:

  • Veri kümesinin displayName öğesini belirtin. displayName değeri tüm veri kümeleri için benzersiz olmalıdır.

  • usage değerini USAGE_DATA_DRIVEN_STYLING olarak ayarlayın.

Örneğin:

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"

Yanıt, veri kümesinin kimliğini projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID biçiminde ve ek bilgilerle birlikte içerir. Veri kümesini güncelleme veya değiştirme isteği gönderirken veri kümesi kimliğini kullanın.

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

Veri kümesine veri yükleme

Veri kümesini oluşturduktan sonra, verileri Google Cloud Storage'dan veya yerel bir dosyadan veri kümesine yükleyin.

Yükleme işlemi eşzamansızdır. Yüklendikten sonra veriler beslenir ve işlenir. Yani, veri kümesinin ne zaman kullanıma hazır olacağını veya herhangi bir hata olup olmadığını belirlemek için veri kümesinin durumunu izlemek üzere bir HTTP GET isteği göndermeniz gerekir. Daha fazla bilgi için Veri işleme durumu alma bölümüne bakın.

Cloud Storage'dan veri yükleme

Veri kümesinin kimliğini de içeren veri kümeleri uç noktasına bir POST isteği göndererek Cloud Storage'dan veri kümenize yükleme yaparsınız:

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

JSON istek gövdesinde:

  • Cloud Storage'da verileri içeren kaynağın dosya yolunu belirtmek için inputUri öğesini kullanın. Bu yol gs://GCS_BUCKET/FILE biçimindedir.

    İsteği gönderen kullanıcının Depolama Alanı Nesnesi Görüntüleyen rolüne veya storage.objects.get iznini içeren başka bir role sahip olması gerekir. Cloud Storage'a erişimi yönetme hakkında daha fazla bilgi için Erişim denetimine genel bakış sayfasını inceleyin.

  • Verilerin dosya biçimini şu şekilde belirtmek için fileFormat kullanın: FILE_FORMAT_GEOJSON (GeoJson dosyası), FILE_FORMAT_KML (KML dosyası) veya FILE_FORMAT_CSV (CSV dosyası).

Örneğin:

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"

Yanıt şu şekildedir:

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

Dosyadan veri yükleme

Bir dosyadan veri yüklemek için datasets uç noktasına, veri kümesinin kimliğini de içeren bir HTTP POST isteği gönderin:

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

İstek şunları içerir:

  • Goog-Upload-Protocol üstbilgisi multipart olarak ayarlanır.

  • Yüklenecek veri türünü belirten bir dosyanın yolunu belirten metadata mülkü: FILE_FORMAT_GEOJSON (GeoJSON dosyası), FILE_FORMAT_KML (KML dosyası) veya FILE_FORMAT_CSV (CSV dosyası).

    Bu dosyanın içeriği aşağıdaki biçimdedir:

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
  • Yüklenecek verileri içeren GeoJSON, KML veya CSV dosyasının yolunu belirten rawdata özelliği.

Aşağıdaki istekte, iki dosyanın yolunu belirtmek için curl -F seçeneği kullanılmıştır:

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"

Yanıt şu biçimdedir:

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

Veri işleme durumunu alma

Yükleme işlemi eşzamansızdır. Yani verileri veri kümesine yükleme API çağrısı döndükten sonra, veri beslemenin ve işlemenin başarılı olup olmadığını belirlemek için veri kümesini yoklamanız gerekir.

Veri kümesinin state değerini belirlemek için Veri kümesi alma'yı kullanın. Örneğin, veriler işlenirken state STATE_PROCESSING olarak ayarlanır. Veri kümesi uygulamanızda kullanıma hazır olduğunda state, STATE_COMPLETED olarak ayarlanır.

Örneğin, veri kümesinde bir GET çağrısı yapın:

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"

Başarılı bir yükleme için veri kümesinin state değeri STATE_COMPLETED olmalıdır:

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

Veri işleme başarısız olduğunda state, STATE_COMPLETED dışında bir değere (ör. STATE_PUBLISHING_FAILED veya _FAILED dizesiyle biten herhangi bir durum) ayarlanır.

Örneğin, bir veri kümesine veri yükler ve ardından veri kümesi ayrıntılarını almak için GET isteği gönderirsiniz. Yanıt, state mülkünün yanı sıra hatanın açıklamasını içeren tek bir errorMessage mülkü de içerir.

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

Veri işleme hataları al

Veri besleme ve işleme başarısız olduğunda errorMessage mülkü, hatayı açıklayan tek bir mesaj içerir. Ancak tek bir hata mesajı, sorunları tanımlayıp çözmek için yeterli bilgi sağlamaz.

Hata bilgilerinin tamamını almak için fetchDatasetErrors API'sini çağırın. Bu API, bir veri kümesiyle ilişkili tüm veri işleme hatalarını döndürür:

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"

Yanıt, errors dizisini içerir. Bu dizi, çağrı başına en fazla 50 Status türünde hata içerir ve toplamda en fazla 500 hatayı destekler:

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

50'den fazla hata varsa (yani birden fazla hata sayfası varsa) yanıtta nextPageToken alanında bir sayfa jetonu bulunur. Bir sonraki hata sayfasını almak için bu değeri sonraki bir çağrının pageToken sorgu parametresine iletin. nextPageToken boş olduğunda başka sayfa olmaz.

Örneğin, önceki yanıttaki jetonu kullanarak sonraki hata sayfasını almak için:

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"

Varsayılan olarak yanıt, sayfa başına en fazla 50 hata içerir. Sayfa boyutunu kontrol etmek için pageSize sorgu parametresini kullanın.

Veri kümesine yeni veri yükleme

Veri kümesini oluşturup ilk verileri başarıyla yükledikten sonra veri kümesinin durumu STATE_COMPLETED olarak ayarlanır. Bu, veri kümesinin uygulamanızda kullanılmaya hazır olduğu anlamına gelir. Veri kümesinin state değerini belirlemek için Veri kümesi alma başlıklı makaleyi inceleyin.

Ayrıca, veri kümesinin yeni bir sürümünü oluşturmak için veri kümesine yeni veriler yükleyebilirsiniz. Yeni veri yüklemek için Cloud Storage'dan veri yükleme veya Veriyi dosyadan yükleme işleminde kullandığınızla aynı süreci uygulayın ve yüklenecek yeni verileri belirtin.

Yeni veriler başarıyla yüklenirse:

  • Veri kümesinin yeni sürümünün durumu STATE_COMPLETED olarak ayarlanır.

  • Yeni sürüm, "etkin" sürüm olur ve uygulamanız tarafından kullanılan sürümdür.

Yüklemede hata varsa:

  • Yeni veri kümesi sürümünün durumu, aşağıdaki durumlardan birine ayarlanır:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED
  • Önceki veri kümesinin başarılı sürümü, "etkin" sürüm olarak kalır ve uygulamanızın kullandığı sürümdür.