Belirli alanları döndür

Bu belgede, Google Drive'da fields parametresinin nasıl kullanılacağı açıklanmaktadı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.

Drive API için geçerli olan diğer sistem parametreleri hakkında bilgi edinmek için Alternatif sistem parametreleri başlıklı makaleyi inceleyin.

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 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 bir hata varsa veya parametre herhangi bir şekilde geçersizse sunucu, alan seçimiyle ilgili neyin yanlış olduğunu belirten bir hata mesajıyla birlikte HTTP 400 Bad Request durum kodu döndürür. Örneğin, files.list(fields='files(id,capabilities,canAddChildren)'), şu hatayı verir: "Invalid field selection 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 temel olarak XPath söz dizimine benzer. Aşağıda, fields parametresiyle ilgili 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 alanı içine yerleştirilmiş b alanını (ör. 'capabilities/canDownload') seçmek için a/b öğesini kullanın. Daha fazla bilgi için İç içe yerleştirilmiş bir kaynağın alanlarını getirme başlıklı makaleyi inceleyin.

  • Dizilerin veya nesnelerin belirli bir alt alan grubunu istemek için bir alt seçici kullanın. İfadeleri parantez içine yazın ("()"). Örneğin, 'permissions(id)', izinler dizisindeki her öğe için yalnızca 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ı (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"
    }
  ]
}

Alternatif sistem parametreleri

Tüm Google Drive API işlemleri için geçerli olan sorgu parametreleri Sistem Parametreleri bölümünde açıklanmıştır.