Belirli alanları döndür

İhtiyacınız olan alanları döndürmek ve performansı artırmak için yöntem çağrınızda fields system parametresini kullanın.

Bu belgede, Google Drive'da fields parametresinin nasıl kullanılacağı açıklanmaktadır.

Alanlar parametresinin işleyiş şekli

fields parametresi, yanıt filtreleme için FieldMask kullanır. Alan maskeleri, bir isteğin döndürmesi gereken alanların bir alt kümesini belirtmek için kullanılır. Gereksiz veri istemediğinizden emin olmak için alan maskesi kullanmak iyi bir tasarım uygulamasıdır. Bu da gereksiz işlem süresini önlemeye yardımcı olur.

fields parametresini belirtmezseniz sunucu, yönteme özgü varsayılan bir alan grubu döndürür. Örneğin, files yöntemindeki list yöntemi yalnızca kind, id, name ve mimeType alanlarını döndürür. permissions kaynağındaki get yöntemi, farklı bir varsayılan alan grubu döndürür.

about, comments (delete hariç) ve replies (delete hariç) kaynaklarının tüm yöntemleri için fields parametresini ayarlamanız gerekir. Bu yöntemler, varsayılan bir alan kümesi döndürmez.

Bir sunucu, fields parametresini içeren geçerli bir isteği işledikten sonra, istenen verilerle birlikte HTTP 200 OK durum kodunu döndürür. Alanlar parametresinde hata varsa veya parametre başka bir şekilde geçersizse sunucu, alan seçimiyle ilgili sorunu belirten bir hata mesajıyla birlikte HTTP 400 Bad Request durum kodunu döndürür. Örneğin, files.list(fields='files(id,capabilities,canAddChildren)'), şu hatayı verir: "Invalid field selection canAddChildren." ("Geçersiz alan seçimi canAddChildren.") Bu örnek için doğru alan parametresi files.list(fields='files(id,capabilities/canAddChildren)')'dır.

fields parametresini kullanarak döndürebileceğiniz alanları belirlemek için sorguladığınız kaynağın dokümanlar sayfasını ziyaret edin. Örneğin, bir dosya için hangi alanları döndürebileceğinizi görmek istiyorsanız files kaynak dokümanlarına bakın. Dosyaya özgü daha fazla sorgu terimi için Arama sorgusu terimleri ve operatörleri başlıklı makaleyi inceleyin.

Alan parametresi biçim kuralları

Alanlar istek parametresi değerinin biçimi, XPath söz dizimine dayanır. Aşağıda, fields parametresinin biçimlendirme kuralları verilmiştir. Bu kuralların tümünde files.get yöntemiyle ilgili örnekler kullanılmaktadır.

  • 'name, mimeType' gibi birden fazla alanı seçmek için virgülle ayrılmış liste kullanın.

  • a/b kullanarak a alanı içinde yerleştirilmiş b alanını (ör. 'capabilities/canDownload') seçin. Daha fazla bilgi için İç içe yerleştirilmiş bir kaynağın alanlarını getirme başlıklı makaleyi inceleyin.

  • İfadeleri parantez içine "()" yerleştirerek dizilerin veya nesnelerin belirli bir alt alan kümesini istemek için alt seçici kullanın. Örneğin, 'permissions(id)' yalnızca izinler dizisindeki her öğe için izin kimliğini döndürür.

  • Bir nesnedeki tüm alanları döndürmek için alan seçimlerinde joker karakter olarak yıldız işareti (*) kullanın. Örneğin, 'permissions/permissionDetails/*', izin başına mevcut tüm izin ayrıntıları alanlarını seçer. Joker karakter kullanmanın istek üzerinde olumsuz performans etkilerine yol açabileceğini unutmayın.

İstek

Bu örnekte, dosya kimliği yol parametresini ve birden fazla alanı istekte sorgu parametresi olarak iletiyoruz. Yanıt, dosya kimliğinin alan değerlerini döndürür.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Yanıt

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

İç içe yerleştirilmiş bir kaynağın alanlarını getirme

Bir alan başka bir kaynağa referans verdiğinde, iç içe yerleştirilmiş kaynağın hangi alanlarının getirilmesi gerektiğini belirtebilirsiniz.

Örneğin, permissions kaynağının role alanını (iç içe yerleştirilmiş kaynak) almak için aşağıdaki seçeneklerden herhangi birini kullanın:

  • fields=role ile permissions.get.
  • permissions.get ile fields=*'ı tıklayarak tüm permissions alanlarını gösterin.
  • files.get, fields=permissions(role) veya fields=permissions/role ile birlikte.
  • files.get ile fields=permissions'ı tıklayarak tüm permissions alanlarını gösterin.
  • fields=changes(file(permissions(role))) ile changes.list.

Birden fazla alanı almak için virgülle ayrılmış liste kullanın. Örneğin, files.list ile fields=files(id,name,createdTime,modifiedTime,size).

İstek

Bu örnekte, dosya kimliği yol parametresini ve iç içe yerleştirilmiş izin kaynağının belirli alanları da dahil olmak üzere birden fazla alanı istekte sorgu parametresi olarak sağlıyoruz. Yanıt, dosya kimliğinin alan değerlerini döndürür.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Yanıt

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}