Belirli alanları döndür

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

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

fields 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 veriler istemediğinizden emin olmak için alan maskesi kullanmak iyi bir tasarım uygulamasıdır. Bu da gereksiz işlem süresinden kaçınmanıza 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 grubu döndürmez.

Bir sunucu, fields parametresini içeren geçerli bir isteği işledikten sonra istenen verilerle birlikte bir HTTP 200 OK durum kodu döndürür. fields parametresinde hata varsa veya geçersizse sunucu, alanlar seçiminizdeki hatayı 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)') "Geçersiz alan seçimi canAddChildren" hatası verir. Bu örnek için doğru fields parametresi files.list(fields='files(id,capabilities/canAddChildren)') olmalıdır.

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

Alan parametresi biçim kuralları

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

  • Birden fazla alan seçmek için virgülle ayrılmış liste kullanın (ör. 'name, mimeType').

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

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

  • Bir nesnenin tüm alanlarını 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. Karıştırıcı karakterin kullanılmasının istek üzerinde olumsuz performans etkilerine yol açabileceğini unutmayın.

Örnek göster

İstek

Bu örnekte, dosya kimliği yol parametresini ve birden fazla alanı istekteki 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

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 getirileceğ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 birini kullanın:

  • fields=role ile permissions.get.
  • Tüm permissions alanlarını göstermek için permissions.get ile fields=*.
  • files.get, fields=permissions(role) veya fields=permissions/role ile birlikte belirtildi.
  • Tüm permissions alanlarını göstermek için files.get ile fields=permissions.
  • 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).

Örnek göster

İ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ı istekteki 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"
    }
  ]
}