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 bir alt kümesini belirtmek için kullanılır. Alan maskesi kullanmak, gereksiz veri istemediğinizden emin olmak için 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 başka bir şekilde geçersizse sunucu, alan seçiminizde 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)') "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ının içine yerleştirilmiş b alanını (ör. 'capabilities/canDownload') seçmek için a/b değerini kullanın. 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 dizi veya nesnelerin belirli bir alt alanını istemek için bir alt seçici kullanın. Örneğin, 'permissions(id)', izin dizisindeki her bir öğe için yalnızca 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 karakter kullanmanın istek üzerinde olumsuz performans etkileri olabileceğ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ği için 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 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.
  • permissions alanın tümünü göstermek için fields=permissions ile files.get().
  • fields=changes(file(permissions(role))) ile changes.list().

Birden çok 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"
    }
  ]
}