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.

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.

Sunucu varsayılan olarak, sorgulanan kaynağa özgü bir alan grubu döndürür. Örneğin, files kaynağındaki get() yöntemi yalnızca id, name ve mimeType öğelerini döndürebilir. permissions kaynağındaki get() yöntemi, farklı bir varsayılan alan grubu döndürür.

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.

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. Joker 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"
    }
  ]
}