Veri kümesi oluşturma

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

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

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

Ön koşullar

Veri kümesi oluştururken:

• Görünen adlar, Google Cloud projeniz içinde benzersiz olmalıdır.
• Görünen adlar 64 bayttan küçük olmalıdır (Bu karakterler UTF-8 olarak temsil edildiği için bazı dillerde her karakter birden fazla bayt ile temsil edilebilir).
• Açıklamaların boyutu 1.000 bayttan az olmalıdır.

Veri yüklerken:

• Desteklenen dosya türleri CSV, GeoJSON ve KML'dir.
• Desteklenen maksimum dosya boyutu 350 MB'tır.
• Özellik sütunu adları "?_" dizesiyle başlayamaz.
• Üç boyutlu geometriler desteklenmez. Buna, WKT biçiminde "Z" son eki ve GeoJSON biçiminde rakım koordinatı dahildir.

Not: Veri dosyasının boyutuna bağlı olarak, yüklemenin tamamlanması birkaç dakika, hatta birkaç saat sürebilir. Yükleme ile ilgili bir hata varsa bir hata mesajı alırsınız. Yükleme işleminden bir yanıt döndürene kadar veri kümesini silmeye çalışmayın.

İpucu: Veri dosyanız büyükse ve stil için ihtiyaç duymadığınız birçok özellik içeriyorsa ve oluşturma performansını optimize etmek istiyorsanız gereksiz özellikleri kaldırmak için dosyayı düzenleyin. Özellik sayısının azaltılması, harita parçalarının boyutunu küçülterek oluşturma performansını iyileştirir.

GeoJSON gereksinimleri

Haritalar Veri Kümeleri API'si, mevcut GeoJSON spesifikasyonunu desteklemektedir. Google Haritalar Veri Kümeleri API'si, aşağıdaki nesne türlerinden herhangi birini içeren GeoJSON dosyalarını da destekler:

• Geometri nesneleri. Geometri nesnesi, noktaların, çizgilerin ve poligonların isteğe bağlı deliklerin birleşimi olarak tanımlanan uzamsal bir şekildir.
• Özellik nesneleri. Bir özellik nesnesi, bir geometri ve ek ad/değer çiftleri içerir. Bunların anlamı uygulamaya özeldir.
• Özellik koleksiyonları. Özellik koleksiyonu, bir dizi özellik nesnesidir.

Maps Datasets API, WGS84 dışında bir koordinat referans sisteminde (CRS) veriler içeren GeoJSON dosyalarını desteklemez.

GeoJSON hakkında daha fazla bilgi için RFC 7946 uyumlu bölümüne bakın.

KML gereksinimleri

Haritalar Veri Kümeleri API'si aşağıdaki şartlara sahiptir:

• Tüm URL'ler dosyanın kendisine yerel (veya ilgili) olmalıdır.
• Nokta, çizgi ve poligon geometrileri desteklenir.
• Tüm veri özellikleri dize olarak kabul edilir.

Aşağıdaki KML özellikleri desteklenmez:

• Dosyanın dışında tanımlanmış simgeler veya <styleUrl>.
• Ağ bağlantıları (ör. <NetworkLink>)
• <GroundOverlay> gibi zemin bindirmeleri
• 3D geometriler veya <altitudeMode> gibi rakımla ilgili etiketler
• <LookAt> gibi kamera özellikleri
• KML dosyasında tanımlanan stiller.

CSV gereksinimleri

CSV dosyaları için desteklenen sütun adları, öncelik sırasına göre aşağıda listelenmiştir:

• latitude, longitude
• lat, long
• x, y
• wkt (İyi Bilinen Metin)
• address, city, state, zip
• address
• Tüm adres bilgilerini içeren tek bir sütun (ör. 1600 Amphitheatre Parkway Mountain View, CA 94043)

Örneğin, dosyanızda x, y ve wkt adlı sütunlar var. Yukarıdaki listede desteklenen sütun adlarının sırasına göre belirlendiği üzere x ve y daha yüksek bir önceliğe sahip olduğu için x ve y sütunlarındaki değerler kullanılır ve wkt sütunu yok sayılır.

Ayrıca:

• Her sütun adı tek bir sütuna ait olmalıdır. Yani hem x hem de y koordinat verilerini içeren xy adlı bir sütununuz olamaz. x ve y koordinatları ayrı sütunlarda olmalıdır.
• Sütun adları büyük/küçük harfe duyarlı değildir.
• Sütun adlarının sırası önemli değildir. Örneğin, CSV dosyanız lat ve long sütunları içeriyorsa bunlar herhangi bir sırada gerçekleşebilir.

Veri yükleme hatalarını işleme

Bir veri kümesine veri yüklerken bu bölümde açıklanan yaygın hatalardan biriyle karşılaşabilirsiniz.

GeoJSON hataları

Yaygın GeoJSON hataları şunlardır:

• type alanı eksik veya type bir dize değil. Yüklenen GeoJSON veri dosyası, her bir Özellik nesnesi ve Geometri nesne tanımının parçası olarak type adlı bir dize alanı içermelidir.

KML hataları

Yaygın KML hataları şunlardır:

• Veri dosyası, yukarıda listelenen desteklenmeyen KML özelliklerinden hiçbirini içermemelidir. Aksi takdirde, verilerin içe aktarılması başarısız olabilir.

CSV hataları

Sık karşılaşılan CSV hataları şunlardır:

• Bazı satırlarda bir geometri sütunu için değerler eksik. Bir CSV dosyasındaki tüm satırlar, geometri sütunları için boş olmayan değerler içermelidir. Geometri sütunları şunları içerir:
  • latitude, longitude
  • lat, long
  • x, y
  • wkt
  • address, city, state, zip
  • address
  • Tüm adres bilgilerini içeren tek bir sütun (ör. 1600 Amphitheatre Parkway Mountain View, CA 94043)
  Not: Bu hata genellikle "' ' öğesi çifte dönüştürülemiyor" veya "Konuma giriş ayrıştırılamadı: Coğrafi değer eksik".
• Geometri sütunlarınız x ve y ise birimlerin enlem ve boylam olduğundan emin olun. Bazı herkese açık veri kümeleri, x ve y başlıklarında farklı koordinat sistemleri kullanır. Yanlış birimler kullanılırsa veri kümesi başarıyla içe aktarılabilir ancak oluşturulan veriler, veri kümesi noktalarını beklenmedik konumlarda gösterebilir.

Veri kümesi oluşturma isteğinde bulunma

Veri kümeleri uç noktasına 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 iletin. Bu politika uyarınca:

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

• usage öğesini USAGE_DATA_DRIVEN_STYLING olarak ayarlayın.

  Not: Şu anda usage için desteklenen tek değer USAGE_DATA_DRIVEN_STYLING'dir.

Ö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 ek bilgilerle birlikte projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID biçiminde içerir. Veri kümesini güncelleme veya değiştirme isteğinde bulunurken 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 isteğinde bulunma

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

Not: Bir veri kümesine yalnızca bir kez veri yükleyebilirsiniz. Yani verileri Cloud Storage'dan veya yerel bir dosyadan yükleme isteğini gerçekleştirdikten sonra aynı veri kümesine tekrar veri yükleyemezsiniz. Yükleme sırasında hata oluşursa veri kümesini yeniden oluşturup tekrar yüklemeyi denemeniz gerekir.

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 isteğinin gövdesinde:

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

  İstekte bulunan kullanıcının Depolama Alanı Nesnesi Görüntüleyici rolünü veya storage.objects.get iznini içeren başka bir rolü olması gerekir. Cloud Storage erişimini yönetme hakkında daha fazla bilgi için Erişim denetimine genel bakış sayfasını inceleyin.

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

Ö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 biçimdedir:

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

Dosyadan veri yükleme

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

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

Not: Bir dosyadan veri yükleme isteği URL'si, Google Cloud Storage'dan veri yükleme URL'sinden farklıdır.

İstek şunları içeriyor:

• Goog-Upload-Protocol başlığı multipart olarak ayarlandı.

• Yüklenecek veri türünü belirten dosyanın yolunu FILE_FORMAT_GEOJSON (GeoJSON dosyası), FILE_FORMAT_KML (KML dosyası) veya FILE_FORMAT_CSV (CSV dosyası) şeklinde belirten metadata özelliği.

  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 istek, iki dosyanın yolunu belirtmek için curl -F seçeneğini kullanı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"
}