Google Sheets API v3'ü temel alan uygulamalarınız varsa Google Sheets API v4'e geçiş yapabilirsiniz. v4 sürümü JSON tabanlıdır, kullanımı daha kolay bir arayüze sahiptir ve v3 sürümünde mümkün olmayan önemli miktarda işlevsellik ekler.
Bu sayfada, eski Sheets API v3 komutları ile Sheets API v4'teki eşdeğer işlemleri arasında bir eşleme bulabilirsiniz. Eşleme büyük ölçüde, doğrudan hücre okuma ve yazma işlevi sağlayan spreadsheets.values koleksiyonuna odaklanır. Sayfa ekleme veya sayfa özelliklerini güncelleme gibi diğer özellikler, e-tablolar koleksiyonu tarafından işlenir. v4 API'nin JSON yapılarının, v3'te kullanılan XML yapılarıyla geriye dönük uyumlu olmadığını unutmayın.
Sheets v4 API'de sunulan kaynaklar hakkında daha fazla bilgi edinmek için API Referansı'na bakın.
Gösterim ve şartlar
v3 API'sı, belirli bir e-tablodaki sayfalar için "çalışma sayfaları" anlamına gelir. Bu, v4 API'sinin kullandığı "sheets" terimiyle eş anlamlıdır.
API'ler genellikle üzerinde çalıştığınız e-tablonun e-tablo kimliğini belirtmenizi gerektirir. Bunlar genellikle değiştirilmekte olan sayfanın kimliğini de gerektirir. Bu değerler, API uç nokta URL'sinin bir parçası, sorgu parametreleri veya istek gövdesinin bir parçası olarak görünür. Bu sayfadaki spreadsheetId ve sheetId yer tutucuları sırasıyla e-tablo ve sayfa kimliklerini ifade eder. Bu sayfada açıklanan yöntemleri kullanırken, ilgili konumlardaki gerçek kimlikleri değiştirin.
v3 API ayrıca liste feed'i kullanılarak alınan satırlara bir kimlik atar. Bu kimlik, bu sayfada rowId yer tutucusuyla gösterilir.
İstekleri yetkilendirme
Uygulamanız çalışırken kullanıcılardan belirli izinleri vermelerini ister. Hangi izinleri istediğini uygulamanızda belirttiğiniz kapsamlar belirler.
v3 API'sı
Sheets API v3, tek bir yetkilendirme kapsamıyla çalışır:
https://spreadsheets.google.com/feeds
Bu,
https://www.googleapis.com/auth/spreadsheets
Her iki kapsam biçimi de kullanılabilir.
v4 API'sı
Sheets API v4, aşağıdaki kapsam gruplarından birini veya daha fazlasını kullanır:
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
Uygulamanızın, bir kullanıcının sayfalarında veya sayfa özelliklerinde düzenleme yapması gerekmiyorsa salt okunur kapsamları kullanın. Uygulama, genel Drive erişimine ihtiyaç duymuyorsa Drive kapsamları yerine e-tablo kapsamlarını kullanın.
Görüş mesafesi
API'nin eski sürümlerinde, görünürlük terimi, belirli bir e-tablonun kullanılabilirliğini belirtmek için kullanılır.
v3 API'sı
Sheets API v3, görünürlüğü doğrudan uç noktalarında ifade eder. Bir public
e-tablosu "Web'de Yayınlanmıştır" ve bu nedenle, API tarafından yetki verilmeden erişilebilir. private
e-tablosu ise kimlik doğrulama gerektirir. Görünürlük, uç noktada e-tablo kimliğinden sonra belirtilir:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
v4 API'sı
Yeni Sheets API v4'te görünürlükle ilgili açık bir beyan yoktur. API çağrıları, e-tablo kimlikleri kullanılarak yapılır. Uygulamanın belirtilen elektronik tabloya erişim izni yoksa bir hata döndürülür. Aksi takdirde, arama devam eder.
Projeksiyon
Projeksiyon terimi, Sheets API v3 tarafından belirli bir API çağrısı tarafından döndürülen veri kümesini (tümü veya API içinde tanımlanmış sabit bir alt küme) ifade etmek için kullanılır. Sheets API v4, projeksiyon kullanmaz. Bunun yerine, hangi verilerin döndürüleceği konusunda daha fazla kontrol sahibi olmanızı sağlar.
v3 API'sı
Sheets API v3'te olası yalnızca iki projeksiyon ayarı vardır. full
projeksiyon, mevcut tüm bilgileri döndürürken basic
, verilerin daha küçük, sabit bir alt kümesini döndürür (çalışma sayfaları, liste ve hücre feed'leri için).
Görünürlük gibi, projeksiyon da API uç noktasında (görünürlük ayarından sonra) belirtilmelidir:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
basic
projeksiyonu tarafından sağlanan daha küçük veri alt kümesi, kodu daha verimli hale getirmek için değerlidir ancak özelleştirilemez.
v4 API'sı
Sheets API v4, tam bir veri kümesi döndürebilir, ancak Sheets API v3'teki basic
görünürlük ayarına benzer şekilde sabit alt kümeler tanımlamaz.
E-tablo koleksiyonundaki yöntemler, fields sorgu parametresi kullanarak döndürdükleri veri miktarını kısıtlar.
Örneğin, aşağıdaki sorgu yalnızca belirli bir e-tablodaki tüm sayfaların başlıklarını döndürür:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
E-tablo oluştur
v3 API'sı
Sheets API v3, yeni e-tablolar oluşturmak için bir araç sağlamaz. Bunun yerine, yeni e-tablo dosyaları oluşturmak için Drive API Files.create yöntemi kullanılabilir. Bunun için uygulamanın https://www.googleapis.com/auth/drive
kapsamını tanımlaması gerekir.
v4 API'sı
Drive API Files.create yöntemi, Sheets API v4 ile de kullanılabilir, ancak uygulamanın https://www.googleapis.com/auth/drive
kapsamını sağlamasını gerektirir.
Eşdeğer bir alternatif olarak Sheets API v4, isteğe bağlı olarak sayfa ekleyebilen, e-tablo ve e-tablo özelliklerini ayarlayabilen ve adlandırılmış aralıklar ekleyebilen bir spreadsheets.create yöntemi sağlar. Örneğin, aşağıdaki örnekte yeni bir e-tablo oluşturulur ve bu e-tablo "YeniBaşlık" adını verir:
POST https://sheets.googleapis.com/v4/spreadsheets
{ "properties": {"title": "NewTitle"} }
Kimliği doğrulanmış kullanıcı için e-tabloları listeleme
v3 API'sı
Sheets API v3 feed'i, bir uygulamanın kimliği doğrulanmış kullanıcı tarafından erişilebilen tüm e-tabloların bir listesini almasına olanak tanır. E-tablo feed'i uç noktası:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API'sı
Sheets API v4, söz konusu işlemi sunmamaktadır. E-tablo seçimi için Google Seçici ile birlikte drive.file kapsamını kullanmak üzere uygulamanızı taşımanızı öneririz.
E-tabloların listelenmesinin gerekli olduğu durumlarda, e-tablolar mimeType
sorgusu kullanılarak Drive API Files.list yöntemiyle çoğaltılabilir:
GET https://www.googleapis.com/drive/v3/files ?q=mimeType='application/vnd.google-apps.spreadsheet'
Bir kullanıcının tüm e-tablolarını listelemek için Drive API files.list yöntemini kullanmak kısıtlanmış bir kapsam gerektirir.
Sayfa meta verilerini alma
Sheets API v3, belirli bir e-tabloda yer alan sayfa meta verilerine (satır ve hücre verilerine ayrı bir feed üzerinden erişilir) erişmek için bir feed sağlar. Meta veriler, sayfa başlıkları ve boyut bilgileri gibi bilgileri içerir.
Sheets API v4 spreadsheets.get yöntemi, bu bilgilere ve çok daha fazlasına erişim sağlar.
v3 API'sı
Çalışma sayfası feed'ine bu API uç noktasından erişilebilir (uygun bir yetkilendirme başlığı kullanılarak):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Bu isteğe verilen yanıtın yapısına benzer bir yapıya sahiptir ve her sayfanın verileri ayrı bir <entry>
içinde barındırılır:
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
v4 API'sı
spreadsheets.get yöntemi, e-tablo özelliklerini ve diğer meta verileri almak için kullanılabilir. E-Tablolar API'si v3'te sunulandan çok daha fazla meta veri içerir. Yalnızca sayfa özelliklerini okumak istiyorsanız e-tablo hücre verilerinin eklenmesini engellemek için includeGridData
sorgu parametresini false
olarak ayarlayın:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Spreadsheet
yanıtı, bir Sheet
nesne dizisi içerir; sayfa başlıkları ve boyut bilgileri özellikle bu nesnelerin SheetProperties
öğesinin altında bulunabilir. Örneğin:
{ "spreadsheetId": spreadsheetId, "sheets": [ {"properties": { "sheetId": sheetId, "title": "Sheet1", "index": 0, "gridProperties": { "rowCount": 100, "columnCount": 20, "frozenRowCount": 1, "frozenColumnCount": 0, "hideGridlines": false }, ... }, ... }, ... ], ... }
E-tabloya sayfa ekleme
Her iki API de mevcut bir e-tabloya yeni sayfa eklemenize olanak tanır.
v3 API'sı
Sheets API v3, aşağıdaki (kimliği doğrulanmış) POST
isteğini göndererek e-tabloya yeni çalışma sayfaları ekleyebilir. Yeni sayfanın boyutunu belirtebilirsiniz:
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
v4 API'sı
spreadsheets.batchUpdate yönteminde bir AddSheet isteği göndererek yeni e-tablolar ekleyebilirsiniz. İstek gövdesinin bir parçası olarak, yeni sayfa için sayfa özelliklerini belirtebilirsiniz. Tüm özellikler isteğe bağlıdır. Mevcut bir sayfa için kullanılan bir başlık girmek hatadır.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [{ "addSheet": { "properties": { "title": "Expenses", "sheetType": "GRID", "gridProperties": { "rowCount": 50, "columnCount": 10 } } } }], }
Sayfa başlığını ve boyutunu değiştirme
Sheets API v3, sayfa başlıklarını ve boyutunu güncellemenize olanak tanır. Sheets API v4, buna da izin verir ancak diğer e-tablo özelliklerini güncellemek için de kullanılabilir. Bir sayfanın boyutunun küçültülmesinin, kırpılmış hücrelerdeki verilerin uyarı yapılmaksızın silinmesine neden olabileceğini unutmayın.
v3 API'sı
Bir çalışma sayfasının başlığını veya boyutunu değiştirmek için öncelikle çalışma sayfası feed'ini alın ve edit
URL'sini içeren istenen çalışma sayfası girişini bulun.
Çalışma sayfasının meta verilerini güncelleyin ve bunu, düzenleme URL'sine bir PUT
isteğinin gövdesi olarak gönderin. Örneğin:
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
v4 API'sı
Boyut, başlık ve diğer e-tablo özelliklerini güncellemek için spreadsheets.batchUpdate yönteminde updateSheetProperties isteğinde bulunun. POST
isteği gövdesi, değiştirilecek özellikleri içermelidir ve fields
parametresi bu özellikleri açıkça listelemelidir (tüm özellikleri güncellemek istiyorsanız tümünü listelemek için kısayol olarak fields:"*"
kullanın). Örneğin, aşağıda belirtilen kimlikle sayfa için sayfa başlığı ve boyut özelliklerinin güncellenmesi gerektiği belirtilmektedir:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "updateSheetProperties": { "properties": { "sheetId": sheetId, "title": "Expenses", "gridProperties": { "rowCount": 45, "columnCount": 15, } }, "fields": "title,gridProperties(rowCount,columnCount)" } } ], }
Bir sayfanın sheetId öğesini almak için e-tablo spreadsheets.get yöntemini kullanın.
Sayfa silme
Her iki API de belirli bir e-tablodan sayfaları kaldırabilir.
v3 API'sı
Bir çalışma sayfasını silmek için öncelikle çalışma sayfası feed'ini alın, ardından hedef çalışma sayfası girişinin edit
URL'si üzerinde bir DELETE
isteği gönderin.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
v4 API'sı
Bir e-tabloyu silmek için spreadsheets.batchUpdate yönteminde DeleteSheet isteğinde bulunun. POST
isteğinin gövdesi, silinecek sayfa için yalnızca sheetId öğesini içermelidir. Örneğin:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteSheet": { "sheetId": sheetId } } ], }
Tek bir sayfanın sheetId öğesini almak için e-tablo spreadsheets.get yöntemini kullanın.
Satır verilerini alma
Satırları listeleme feed'i, Sheets API v3'ün bir e-tablonun hücrelerindeki (diğeri hücre feed'i) verilere erişmek için sunduğu iki yöntemden biridir. Satır feed'inin amacı, yaygın e-tablo işlemlerini (satır satır okuma, satır ekleme, sıralama) desteklemesi olsa da bazı varsayımlarda bulunarak bu işlemleri bazı görevler için engellemektedir. Özellikle liste feed'i, boş satırların feed sonlandırmaları olduğunu ve bir sayfanın ilk satırında zorunlu başlıkların bulunduğunu varsayar.
Öte yandan, Sheets API v4, satıra özel erişim yöntemlerini kullanmaz. Bunun yerine, e-tablo hücre verilerine A1 notasyonu kullanılarak gerekli belirli aralıklar referans alınarak erişilir. Aralıklar, hücre blokları, satırların tamamı, sütunların tamamı veya sayfaların tamamı olabilir. API, ayrı hücre gruplarına da erişebilir.
v3 API'sı
Belirli bir çalışma sayfası için liste tabanlı bir yayının URL'sini belirlemek üzere çalışma sayfası feed'ini alın ve ilgili çalışma sayfası girişindeki liste feed'i URL'sini bulun.
Listeye dayalı bir feed almak için uygun bir yetkilendirme başlığı kullanarak liste feed'i URL'sine bir GET
isteği gönderin. Örneğin:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Bu isteğe verilen yanıt, diğer unsurların yanı sıra, belirli satırlara karşılık gelen girişleri içerir. Hücrelere tek tek, (zorunlu) sayfa başlığı satırında sağlanan adlarla başvurulur. Örneğin, burada tek bir satır girişi görebilirsiniz:
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
Varsayılan olarak, liste feed'inde döndürülen satırlar satır sırasına göre döndürülür. Sheets API v3, bu sırayı değiştirmek için sorgu parametreleri sağlar.
Ters sırada:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Belirli bir sütuna göre sırala:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?orderby=column:lastname
Sheets API v3, yapılandırılmış bir sorgu aracılığıyla belirli satırların filtrelenmesine de olanak tanır (sütun başlıklarıyla referans verilmiştir):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?sq=age>25%20and%20height<175
v4 API'sı
Sheets API v4'te satırlar, spreadsheets.values.get veya spreadsheets.values.batchGet yöntemleri kullanılarak aralığa göre alınabilir. Örneğin, aşağıdaki işlem "Sheet1" içindeki tüm satırları döndürür:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Bu isteğe verilen yanıtın yapısı şuna benzer:
{ "range": "Sheet1", "majorDimension": "ROWS", "values": [["Name", "Hours", "Items", "IPM"], ["Bingley", "10", "2", "0.0033"], ["Darcy", "14", "6", "0.0071"]] }
Satırların, sütunların veya sayfaların tamamı alınırken sondaki boş hücreler yanıta dahil edilmez.
Sheets API v4'te, Sheets API v3 tarafından sağlanan satır sırası sorgu parametrelerinin eşdeğerleri yoktur. Ters sıra önemsizdir. Döndürülen values
dizisini ters sırada işlemeniz yeterlidir. Sütuna göre sıralama, okumalarda desteklenmez ancak sayfadaki verileri sıralamak (bir SortRange kullanarak) ve daha sonra okumak mümkündür.
Sheets API v4'ün, Sheets API v3 yapılandırılmış sorgularıyla doğrudan eşdeğeri yoktur. Bununla birlikte, ilgili verileri alabilir ve uygulamanızda gerektiği şekilde sıralayabilirsiniz.
Yeni bir veri satırı ekleme
API'lerden birini kullanarak e-tabloya yeni bir veri satırı ekleyebilirsiniz.
v3 API'sı
Belirli bir çalışma sayfası için liste tabanlı bir yayının URL'sini belirlemek üzere çalışma sayfası feed'ini alın ve ilgili çalışma sayfası girişindeki yayının URL'sini bulun.
Bir veri satırı eklemek için uygun bir yetkilendirme başlığı kullanarak yayın URL'sine POST
isteği gönderin. Örneğin:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
POST
isteğinin gövdesi, sütun başlıkları tarafından referans verilen tek tek hücrelerle birlikte, eklenecek satır verileri için bir giriş içermelidir:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
Yeni satırlar, belirtilen sayfanın sonuna eklenir.
v4 API'sı
Sheets API v4'te spreadsheets.values.append yöntemini kullanarak satır ekleyebilirsiniz. Aşağıdaki örnekte, bir e-tablonun "Sheet1" bölümündeki son tablonun altına yeni bir veri satırı yazılmaktadır.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Ayrıca Sheets API v4, bir spreadsheets.batchUpdate dosyasındaki AppendCells isteklerini kullanarak belirli özelliklere ve biçimlendirmeye sahip hücreler eklemenize de olanak tanır.
Yeni veriler içeren bir satırı düzenleme
Her iki API de satır verilerinin yeni değerlerle güncellenmesine izin verir.
v3 API'sı
Bir veri satırını düzenlemek üzere güncellemek istediğiniz satıra ait girişi bulmak için liste feed'ini inceleyin. Bu girişin içeriğini gerektiği gibi güncelleyin. Kullandığınız girişteki kimlik değerinin mevcut girişin kimliğiyle tam olarak eşleştiğinden emin olun.
Giriş güncellendikten sonra, uygun bir yetkilendirme başlığı kullanarak söz konusu satır girişinde sağlanan edit
URL'sine istek gövdesi olarak girişi içeren bir PUT
isteği gönderin. Örneğin:
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
v4 API'sı
Sheets API v4 ile, düzenlemek istediğiniz satırın A1 gösterimini kullanarak bir satırı düzenleyebilir ve bu satırın üzerine yazmak için bir spreadsheets.values.update isteği gönderebilirsiniz. Belirtilen aralığın yalnızca satırdaki ilk hücreye başvuruda bulunması gerekir. API, istekle sağlanan değerlere göre güncellenecek hücreleri tahmin eder. Bunun yerine çok hücreli bir aralık belirtirseniz sağladığınız değerlerin bu aralığa sığması gerekir. Aksi takdirde, API hata döndürür.
Aşağıdaki örnek istek ve istek gövdesi, "Sheet1" öğesinin dördüncü satırına veri ekler:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Satır verilerini spreadsheet.values.batchUpdate yönteminden de güncelleyebilirsiniz. Birden çok satır veya hücre güncellemesi yapıyorsanız bu yöntemi kullanmak daha verimlidir.
E-Tablolar API'si v4 ayrıca, spreadsheets.batchUpdate'deki UpdateCells veya RepeatCell istekleri kullanılarak hücre özelliklerini ve biçimlendirmeyi düzenlemenize de olanak tanır.
Satır silme
Her iki API de satırların silinmesini destekler. Silinen bir satır e-tablodan kaldırılır ve bunun altındaki satırlar bir satıra aktarılır.
v3 API'sı
Bir satırı silmek için önce liste feed'inden silinecek satırı alın, ardından satırın girişinde sağlanan edit
URL'sine bir DELETE
isteği gönderin.
Bu, satırı güncellemek için kullanılan URL'nin aynısıdır.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Başka bir istemci tarafından değiştirilmiş bir satırı aldığınızdan beri silmediğinizden emin olmak istiyorsanız, orijinal satırın ETag değerini içeren bir HTTP If-Match başlığı ekleyin. Orijinal satırın ETag değerini, giriş öğesinin gd:etag özelliğini inceleyerek belirleyebilirsiniz.
Siz aldıktan sonra başka birinin güncellemiş olup olmadığına bakılmaksızın satırı silmek istiyorsanız If-Match: * kullanın ve ETag'i eklemeyin. (Bu durumda, satırı silmeden önce geri almanız gerekmez.)
v4 API'sı
Sheets API v4 ile satırların silinmesi, DeleteDimension isteği kullanılarak bir spreadsheet.batchUpdate yöntem çağrısı tarafından gerçekleştirilir. Bu istek, sütunları ve geliştiricileri kaldırmak ve bir satırın veya sütunun yalnızca bir kısmını kaldırmayı seçmek için de kullanılabilir. Örneğin, aşağıda belirtilen kimliğe sahip bir sayfanın 6. satırı kaldırılır (satır dizinleri startIndex dahil ve endIndex hariç olmak üzere sıfır tabanlıdır):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteDimension": { "range": { "sheetId": sheetId, "dimension": "ROWS", "startIndex": 5, "endIndex": 6 } } } ], }
Bir e-tablonun sheetId öğesi, spreadsheet.get yöntemi kullanılarak alınabilir.
Hücre verilerini alma
Sheets API v3, bir e-tabloda depolanan tüm verilere temel erişim için hücre feed'i sağlar. Okuma erişimi için hücre feed'i, sayfa içeriğinin tamamını veya bir dizi sorgu parametresiyle tanımlanan sayfadaki hücre aralığını sağlayabilir, ancak bunu yalnızca tek bir blok halinde sağlayabilir. Ayrı aralıkları, ek GET
istekleri kullanılarak ayrı olarak alınmalıdır.
Sheets API v4, bir sayfadan herhangi bir hücre veri kümesini (birden fazla ayrık aralık dahil) alabilir. Sheets API v3, hücre içeriklerini yalnızca giriş değerleri (klavyede kullanıcının gireceği gibi) ve/veya formül çıktıları (sayısalsa) olarak döndürebilir. E-Tablolar API'si v4; değerlere, formüllere, biçimlendirmeye, köprülere, veri doğrulamaya ve diğer özelliklere tam erişim izni verir.
v3 API'sı
Belirli bir çalışma sayfası için hücre tabanlı feed'in URL'sini belirlemek üzere, çalışma sayfası feed'ini inceleyin ve ilgili çalışma sayfası girişinde hücre feed'i URL'sini bulun.
Hücre tabanlı feed almak için uygun bir yetkilendirme başlığı kullanarak hücre feed'i URL'sine bir GET
isteği gönderin. Örneğin:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Hücrelere, satır ve sütun numarası kullanılarak başvuruluyor. max-row
, min-row
, max-col
ve min-col
sorgu parametreleri kullanılarak belirli bir aralık alınabilir. Örneğin, aşağıda 2. satırdan başlayarak 4. sütundaki (D) tüm hücreler alınır:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full ?min-row=2&min-col=4&max-col=4
Sheets API v3, alınan hücrelerin inputValue
değerini döndürür. Bu değer, kullanıcının hücreyi değiştirmek için Google E-Tablolar kullanıcı arayüzüne yazacağı değerdir. inputValue
sabit bir değer veya formül olabilir. API bazen bir numericValue
döndürür (örneğin, bir formül sayı sağladığında). Örneğin, bir yanıt aşağıdakine benzer yapıda hücre girişleri içerebilir:
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
v4 API'sı
İlgili aralık veya aralıklar için sırasıyla bir spreadsheets.values.get veya spreadsheets.values.batchGet yöntemini çağırarak hücre verilerini alın. Örneğin, aşağıda "Sayfa2"nin D sütunundaki hücreleri, 2. satırdan başlayarak sütun ana düzenine göre ve formülleri girildiği şekilde döndürerek döndürür (sondaki boş hücreler atlanır):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Bu talebe verilen yanıtın yapısı aşağıdakine benzer:
{ "spreadsheetId": spreadsheetId, "valueRanges": [ {"range": "Sheet2!D2:D", "majorDimension": "COLUMNS", "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]] }] }
Birden çok hücre verisi aralığı almayı planlıyorsanız spreadsheet.values.batchGet kullanmak daha verimlidir. Biçimlendirme gibi hücre özelliklerine erişmek istiyorsanız spreadsheet.get yöntemi gereklidir.
Hücreyi düzenleme
Sheets API v3, değiştirilmiş hücre girişini istek gövdesi olarak içeren hücre feed'ine bir PUT
komutu göndererek hücre içeriğini düzenlemenize olanak tanır.
Öte yandan Sheets API v4, hücre içeriğini değiştirmek için spreadsheets.values.update ve spreadsheets.values.batchUpdate yöntemlerini sağlar.
v3 API'sı
Tek bir hücrenin içeriğini düzenlemek için önce hücre feed'inde hücrenin girişini bulun.
Giriş, bir düzenleme URL'si içeriyor. Girişi, hücrenin sahip olmasını istediğiniz içeriği yansıtacak şekilde güncelleyin ve ardından, isteğin gövde bölümü olarak güncellenmiş hücre girişini kullanarak URL düzenleme URL'sine bir PUT
isteği gönderin. Örneğin, aşağıdaki formül D2 (R2C4) hücresini bir SUM
formülü içerecek şekilde günceller:
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
v4 API'sı
Sheets API v4'te tek hücreli düzenleme, spreadsheets.values.update yöntemiyle yapılabilir. Bu yöntem için ValueInputOption
sorgu parametresi gerekir. Bu parametre, giriş verilerinin E-Tablolar kullanıcı arayüzüne (USER_ENTERED
) girilmiş gibi mi değerlendirileceğini yoksa ayrıştırılmadan ayrılıp olduğu gibi mi alınacağını (RAW
) mı olacağını belirtir. Örneğin, aşağıdaki D2 hücresi bir formülle güncellenir:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}
Birden çok hücrede düzenleme yapıyorsanız bunları tek bir istekte yayınlamak için spreadsheets.values.batchUpdate yöntemini kullanın.
Toplu istekle birden fazla hücreyi düzenleme
Her iki API de tek bir (toplu) istekle birden fazla hücrenin içeriğinde değişiklik yapma olanağı sunar. Toplu istek tarafından başvuruda bulunulan hücrelerin koşullu bir aralıkta olması gerekmez.
Toplu grupta bir veya daha fazla hücre düzenlemesinin başarısız olması durumunda Sheets API v3, diğerlerinin başarılı olmasına olanak tanır. Ancak, toplu güncellemelerden herhangi biri başarısız olursa Sheets API v4 bir hata döndürür ve bu durumda hiçbirini uygulamaz.
v3 API'sı
Birden çok hücreyi düzenlemek için önce çalışma sayfası için bir hücre feed'i alın. Giriş bir toplu URL içeriyor. Bu URL'ye, güncellemek istediğiniz hücreleri ve yeni hücre içeriğini açıklayan bir istek gövdesiyle birlikte POST
isteği gönderin. POST
isteği ve istek gövdesi, aşağıdakine benzer bir yapıya sahiptir:
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
batch:id
alanı, gruptaki isteği benzersiz bir şekilde tanımlamalıdır.
Hücre düzenlemeleri için batch:operation
alanı update
olmalıdır. gs:cell
, hücreyi satır ve sütun numarasına göre tanımlar ve buraya eklenecek yeni verileri sağlar. id
, güncellenecek hücrenin tam URL'sini içerir.
link
, hücre kimliğine giden tam yolu içeren bir href
özelliğine sahip olmalıdır. Her giriş için bu alanların tümü zorunludur.
v4 API'sı
Sheets API v4, spreadsheets.values.batchUpdate yöntemi ile hücre değerlerinin toplu olarak düzenlenmesini sağlar.
İstek gövdesinde belirtilen veri değişikliklerini içeren bir POST
isteği gönderilerek birden çok hücre düzenlenebilir. Örneğin:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{ "valueInputOption": "USER_ENTERED" "data": [ {"range": "D4", "majorDimension": "ROWS", "values": [["newData"]] }, {"range": "B5", "majorDimension": "ROWS", "values": [["moreInfo"]] } ] }
Aralık olarak tek bir hücre belirttiyseniz sağlanan tüm değerler, bu hücreden sol üst koordinat olarak başlayacak şekilde sayfaya yazılır. Bunun yerine çok hücreli bir aralık belirtirseniz sağladığınız değerlerin bu aralığa tam olarak uyması gerekir. Aksi takdirde API hata döndürür.