Google Sheets API v3'ü temel alan uygulamalarınız varsa Google Sheets API v4'e geçebilirsiniz. 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 büyük miktarda işlev ekler.
Bu sayfada, eski Sheets API v3 komutları ile Sheets API v4'teki eşdeğer işlemler arasında eşleme sağlanmaktadır. 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 işlemler e-tablolar koleksiyonunda ele alınır. 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 bulunan kaynaklar hakkında daha fazla bilgi için API Referansı'nı inceleyin.
Gösterim ve şartlar
v3 API, belirli bir e-tablodaki sayfaları "çalışma sayfaları" olarak belirtir. Bu terim, v4 API'nin kullandığı "sayfalar" terimiyle eş anlamlıdır.
API'ler genellikle üzerinde çalıştığınız e-tablonun e-tablo kimliğini belirtmenizi gerektirir. Ayrıca, genellikle değiştirilmekte olan sayfanın kimliğini de gerektirir. Bu değerler API uç nokta URL'sinin veya sorgu parametreleri olarak ya da istek gövdesinin bir parçası olarak görünür. Bu sayfada, spreadsheetId ve sheetId yer tutucuları sırasıyla e-tablo ve sayfa kimliklerini ifade etmektedir. Bu sayfada açıklanan yöntemleri kullanırken, bu konumlardaki gerçek kimlikleri değiştirin.
v3 API, liste feed'ini kullanarak alınan satırlara da bir kimlik atar. Bu, bu sayfada rowId yer tutucusuyla temsil edilir.
İstekleri yetkilendirme
Uygulamanız çalışırken kullanıcılardan belirli izinleri vermelerini ister; uygulamanızda belirttiğiniz kapsamlar, hangi izinleri istediğini belirler.
v3 API'sı
Sheets API v3, tek bir yetkilendirme kapsamıyla çalışır:
https://spreadsheets.google.com/feeds
Bu, Google’ın
https://www.googleapis.com/auth/spreadsheets
Her iki kapsam biçimi de kullanılabilir.
v4 API'sı
Sheets API v4, aşağıdaki kapsamlardan 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 e-tablo veya e-tablo ö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ünürlük
API'nin eski sürümlerinde görünürlük terimi, belirli bir e-tablonun kullanılabilirliğini ifade etmek 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". Bu nedenle API, yetkisiz bir şekilde erişilebilirken private e-tablosu kimlik doğrulama gerektirir. Görünürlük, uçta 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 e-tabloya erişim izni yoksa bir hata döndürülür. Aksi takdirde görüşme devam eder.
Projeksiyon
Projeksiyon terimi, Sheets API v3 tarafından belirli bir API çağrısı tarafından (tamamı veya API içinde tanımlanan sabit bir alt küme) döndürülen veri kümesini belirtmek için kullanılır. Sheets API v4, projeksiyon kullanmaz. Bunun yerine, hangi verilerin döndürüleceği üzerinde daha fazla kontrol sahibi olmanızı sağlar.
v3 API'sı
Sheets API v3'te yalnızca iki olası projeksiyon ayarı vardır. full projeksiyonu mevcut tüm bilgileri döndürürken basic daha küçük ve sabit bir veri alt kümesi (çalışma sayfaları, liste ve hücre feed'leri için) döndürür.
Görünürlük gibi, projeksiyon da API uç noktasında belirtilmelidir (görünürlük ayarından sonra):
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 açısından değerlidir ancak özelleştirilemez.
v4 API'sı
Sheets API v4, tam bir veri kümesi döndürebilir ancak E-Tablolar API v3'teki basic görünürlük ayarına benzer şekilde sabit alt kümeler tanımlamaz.
E-tablo koleksiyonundaki yöntemler, bir fields sorgu parametresinin kullanımı aracılığıyla 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-tablo 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. Bu, uygulamanın https://www.googleapis.com/auth/drive kapsamını beyan etmesini gerektirir.
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ı gerekir.
Eşdeğer bir alternatif olarak Sheets API v4, isteğe bağlı olarak e-tablo ekleme, e-tablo ve e-tablo özelliklerini ayarlama ve adlandırılmış aralıklar ekleme işlemlerini yapabilen bir spreadsheets.create yöntemi sağlar. Örneğin, aşağıda yeni bir e-tablo oluşturulur ve buna "NewTitle" adı verilir:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Kimliği doğrulanmış kullanıcı için e-tabloları listele
v3 API'sı
Sheets API v3 feed'i, uygulamanın kimliği doğrulanmış kullanıcı tarafından erişilebilen tüm e-tabloların listesini almasına olanak tanır. E-tablo feed'i uç noktası şöyledir:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API'sı
Sheets API v4, bu işlemi gerçekleştirmez. E-tablo seçimi için Drive.file kapsamını Google Picker ile birlikte kullanmak için uygulamanızı taşımanızı öneririz.
E-tabloları listelemenin gerekli olduğu durumlarda, e-tablolar Drive API Files.list yöntemi aracılığıyla bir mimeType sorgusu kullanılarak ç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-tablodaki sayfa meta verilerine erişmek için bir feed sağlar (satır ve hücre verilerine ayrı bir feed üzerinden erişilir). 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 (uygun bir yetkilendirme başlığı kullanılarak) erişilebilir:
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Bu isteğe verilen yanıt şuna benzer bir yapıya sahiptir ve her sayfanın verileri ayrı bir <entry> içinde yer alı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-Tablolar API v3 ile kullanılabilenlerden çok daha fazlasını, sayfa özelliklerini ve diğer meta verileri edinmek için kullanabilir. Yalnızca sayfa özelliklerini okumak istiyorsanız e-tablo hücre verilerinin dahil edilmesini önlemek 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 sayfalar 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 sayfalar ekleyebilirsiniz. İstek gövdesinin bir parçası olarak, yeni e-tablonun 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 ise buna da olanak tanır ancak diğer sayfa özelliklerini güncellemek için de kullanılabilir. Bir sayfanın boyutunu küçültmenin, kırpılmış hücrelerdeki verilerin uyarı yapılmaksızın silinmesine neden olabileceğini unutmayın.
v3 API'sı
Ç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 istediğiniz çalışma sayfası girişini bulun.
Çalışma sayfasının meta verilerini güncelleyin ve PUT isteğinin gövdesi olarak
düzenleme URL'sine 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 sayfa özelliklerini güncellemek için spreadsheets.batchUpdate yönteminde bir updateSheetProperties isteğinde bulunun. POST istek gövdesi, değiştirilecek özellikleri içermeli ve fields parametresi bu özellikleri açıkça listelemelidir (tüm özellikleri güncellemek istiyorsanız hepsini listelemek için kısaltılmış kelime olarak fields:"*" kullanın). Örneğin aşağıdaki örnek, belirtilen kimliğe sahip sayfa için sayfa başlığı ve boyut özelliklerinin güncellenmesi gerektiğini belirtir:
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 sayfasını almak için e-tablo spreadsheets.get yöntemini kullanın.
Sayfa silme
Her iki API de belirli bir e-tablodan sayfa kaldırabilir.
v3 API'sı
Bir çalışma sayfasını silmek için işe çalışma sayfası feed'ini alarak başlayın, ardından hedef çalışma sayfası girişinin edit URL'sinde bir DELETE isteği gönderin.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
v4 API'sı
Bir sayfayı silmek için spreadsheets.batchUpdate yönteminde bir DeleteSheet isteğinde bulunun. POST istek gövdesi, yalnızca silinecek sayfa için sheetId içermelidir. Örneğin:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Tek bir e-tablonun sheetId öğesini almak için e-tablo spreadsheets.get yöntemini kullanın.
Satır verilerini alma
Liste satırları feed'i, Sheets API v3'ün e-tablo hücrelerindeki verilere erişmek için sunduğu iki yöntemden biridir (diğeri, hücre feed'idir). Satır feed'i, yaygın e-tablo işlemlerini (satır satır okuma, satır ekleme, sıralama) desteklemeyi amaçlar ancak bazı görevler için uygun olmayan bazı varsayımlar sunar. Liste feed'i, boş satırların feed sonlandırma olduğunu ve sayfanın ilk satırında zorunlu başlıkların bulunduğunu varsayar.
Öte yandan, Sheets API v4 satıra özgü erişim yöntemleri kullanmaz. Bunun yerine, sayfa hücresi verilerine A1 gösterimi ile gereken belirli aralıklara başvurularak erişilir. Aralıklar; hücre blokları, satırların tamamı, sütunların tamamı veya sayfaların tamamı olabilir. API ayrık hücre kümelerine de erişebilir.
v3 API'sı
Belirli bir çalışma sayfasındaki listeye dayalı feed'in URL'sini belirlemek için çalışma sayfası feed'ini alın ve ilgili çalışma sayfası girişinde liste feed'i URL'sini bulun.
Liste tabanlı 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ğerlerinin yanı sıra belirli satırlara karşılık gelen girişler içerir. Bağımsız hücrelere, (zorunlu) sayfa başlığı satırında sağlanan adlar başvuruda bulunur. Örneğin, burada tek satırlı bir giriş 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ıralama:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastname
Sheets API v3, yapılandırılmış bir sorguyla belirli satırların filtrelenmesine de olanak tanır (sütun başlıklarıyla referans verilir):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 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 "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 aşağıdakine benzer bir yapıya sahiptir:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Satır, sütun veya sayfaların tamamı alınırken sonraki boş hücreler yanıta dahil edilmez.
Sheets API v4'te, Sheets API v3 tarafından sağlanan satır sırası sorgu parametrelerine eşdeğer eşdeğerleri yoktur. Ters sıra önemsizdir; döndürülen values dizisini ters sırada işlemeniz yeterlidir. Okumalar için sütuna göre sıralama desteklenmez ancak sayfadaki verileri sıralamak (SortRange isteği kullanarak) ve ardından okumak mümkündür.
Sheets API v4 şu anda Sheets API v3 yapılandırılmış sorguları için doğrudan bir eşdeğeri yoktur. Bununla birlikte, ilgili verileri alabilir ve uygulamanızda gereken şekilde sıralayabilirsiniz.
Yeni bir veri satırı ekleme
API'lerden birini kullanarak bir sayfaya yeni bir veri satırı ekleyebilirsiniz.
v3 API'sı
Belirli bir çalışma sayfasındaki listeye dayalı feed'in URL'sini belirlemek için çalışma sayfası feed'ini alın ve ilgili çalışma sayfası girişinde yayın URL'sini bulun.
Bir veri satırı eklemek için uygun bir yetkilendirme başlığı kullanarak yayın URL'sine bir POST isteği gönderin. Örneğin:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
POST isteğinin gövdesinde, sütun başlıkları tarafından başvurulan bağımsız hücrelerle birlikte eklenecek satır verileri için bir giriş bulunmalıdır:
<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 "Sayfa1" bölümündeki son tablonun altına yeni bir veri satırı yazmaktadır.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Ayrıca, Sheets API v4, spreadsheets.batchUpdate içindeki AppendCells isteklerini kullanarak belirli özelliklere ve biçimlendirmeye sahip hücreleri eklemenize de olanak tanır.
Yeni verilerin bulunduğu bir satırı düzenleme
Her iki API de satır verilerinin yeni değerlerle güncellenmesine olanak tanır.
v3 API'sı
Bir veri satırını düzenlemek için liste feed'ini inceleyerek güncellemek istediğiniz satıra ait girişi bulun. Bu girişin içeriğini gerektiğinde 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'te, 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, güncelleme yapılacak hücreleri istekle birlikte sağlanan değerlere dayanarak belirler. Bunun yerine çok hücreli bir aralık belirtirseniz sağladığınız değerler bu aralığa sığmalıdır. Aksi takdirde, API hata döndürür.
Aşağıdaki örnek istek ve istek gövdesi, verileri "Sheet1"in dördüncü satırına 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 fazla satır ya da hücre güncellemesi yapıyorsanız bu yöntemi kullanmak daha verimli olur.
Ayrıca, Sheets API v4, spreadsheets.batchUpdate içindeki UpdateCells veya RepeatCell isteklerini kullanarak hücre özelliklerini ve hücreleri biçimlendirmenizi de sağlar.
Satır silme
Her iki API de satırların silinmesini destekler. Silinen bir satır e-tablodan kaldırılır ve altındaki satırlar bir yukarıya 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 girişinde sağlanan edit URL'sine bir DELETE isteği gönderin.
Bu, satırı güncellemek için kullanılan URL'dir.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Geri aldığınızdan beri başka bir istemci tarafından değiştirilen bir satırı silmediğinizden emin olmak istiyorsanız orijinal satırın ETag değerini içeren bir HTTP If-Match başlığı ekleyin. Giriş öğesinin gd:etag özelliğini inceleyerek orijinal satırın ETag değerini belirleyebilirsiniz.
Satırı, siz aldığınızdan sonra başka birinin güncellemiş olup olmadığından bağımsız olarak silmek istiyorsanız If-Match: * işlevini kullanın ve ETag'i eklemeyin. (Bu durumda, satırı silmeden önce geri almanız gerekmez.)
v4 API'sı
E-Tablolar API v4 ile satırların silinmesi, DeleteDimension isteği kullanılarak spreadsheet.batchUpdate yöntem çağrısı tarafından gerçekleştirilir. Bu istek, sütunları kaldırmak ve geliştiriciler için de kullanılabilir ve bir satır veya sütunun yalnızca bir kısmını kaldırmayı seçebilir. Örneğin, aşağıdaki işlemler, belirtilen kimliğe sahip bir sayfanın 6. satırını kaldırır (satır dizinleri sıfır tabanlıdır ve startIndex'i içerir ve endIndex hariçtir):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Bir sayfanın sheetId değeri, 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 bir hücre feed'i sağlar. Okuma erişimi için hücre feed'i, bir dizi sorgu parametresi tarafından tanımlanan sayfa içeriğinin tamamını veya sayfa hücre aralığını sağlayabilir. Ancak bu yalnızca tek bir blok halinde sunulur. Ayrık aralıkların, ek GET istekleri kullanılarak ayrı olarak alınması gerekir.
Sheets API v4, bir sayfadaki herhangi bir hücre verisi grubunu (birden fazla ayrık aralık dahil) alabilir. Sheets API v3, hücre içeriklerini yalnızca giriş değerleri (kullanıcının klavyeden girebileceği şekilde) ve/veya formül çıkışları (sayısalsa) olarak döndürebilir. Sheets API v4 ise değerler, formüller, biçimlendirme, köprüler, veri doğrulaması ve diğer özelliklere tam erişim izni verir.
v3 API'sı
Belirli bir çalışma sayfasındaki hücre tabanlı feed'in URL'sini belirlemek için çalışma sayfası feed'ini inceleyin ve ilgili çalışma sayfası girişinde hücre feed'i URL'sini bulun.
Hücre tabanlı bir 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şvuruda bulunulur. max-row, min-row, max-col ve min-col sorgu parametreleri kullanılarak tek bir belirli aralık getirilebilir. Örneğin, aşağıda 2. satırdan başlayarak 4. sütundaki (D) tüm hücreleri alı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, değişmez değer veya formül olabilir. API bazen bir numericValue döndürür. Örneğin, bir formül sayı ile sonuçlandığında. Örneğin, bir yanıt, yapı olarak aşağıdakine benzer 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 spreadsheets.values.get veya spreadsheets.values.batchGet yöntemini çağırarak hücre verilerini alın. Örneğin, aşağıdaki formül, "Sayfa2"nin D sütunundaki hücreleri sütun ana sırasına göre 2. satırdan başlayacak şekilde ve formülleri girildiği şekilde döndürür (sonraki boş hücreler atlanır):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Bu isteğe verilen yanıt yapı olarak şuna benzer:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}
Birden fazla 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 kullanmanız gerekir.
Hücreyi düzenleme
Sheets API v3, değiştirilmiş hücre girişini istek gövdesi olarak içerecek şekilde hücre feed'ine bir PUT komutu göndererek hücre içeriğini düzenlemenize olanak tanır.
E-Tablolar API v4 ise bunun aksine, hücre içeriğini değiştirmek için spreadsheets.values.update ve spreadsheets.values.batchUpdate yöntemleri 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ücrede bulunmasını istediğiniz içerikleri yansıtacak şekilde güncelleyin ve ardından, isteğin gövdesi olarak güncellenmiş hücre girişini içeren düzenleme URL'sine bir PUT isteği gönderin. Örneğin, aşağıdaki hücre 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öntemi kullanılarak yapılabilir. Bu yöntem, giriş verilerinin E-Tablolar kullanıcı arayüzüne (USER_ENTERED) girilmiş gibi ele alınacağını veya ayrıştırılmamış ve olduğu gibi alınıp alınacağını (RAW) belirten bir ValueInputOption sorgu parametresi gerektirir. Ö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ücre düzenlemesi yapıyorsanız bunları tek bir istekte yayınlamak için spreadsheets.values.batchUpdate yöntemini kullanın.
Toplu istek aracılığıyla birden fazla hücreyi düzenleme
Her iki API de tek bir (toplu) istekle birden çok hücrenin içeriğinde değişiklik yapmaya olanak tanır. Toplu istek tarafından başvuruda bulunulan hücrelerin koşullu bir aralıkta olmaları gerekmez.
Toplu işlemdeki bir veya daha fazla hücre düzenlemesinin başarısız olması durumunda Sheets API v3 diğerlerinin başarılı olmasını sağlar. Ancak, toplu güncellemelerden herhangi biri başarısız olursa Sheets API v4 hata döndürür ve bu durumda hiçbirini uygulamaz.
v3 API'sı
Birden fazla 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. Güncellemek istediğiniz hücreleri ve yeni hücre içeriğini açıklayan bir istek metniyle birlikte, bu URL'ye bir 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 oraya eklenecek yeni verileri sağlar. id, güncellenecek hücrenin tam URL'sini içerir.
link, hücre kimliğinin tam yolunu içeren bir href özelliğine sahip olmalıdır. Bu alanların tümü her giriş için zorunludur.
v4 API'sı
Sheets API v4, spreadsheets.values.batchUpdate yöntemi aracılığıyla hücre değerlerinin toplu olarak düzenlenmesini sağlar.
İstek gövdesinde belirtilen veri değişikliklerine sahip bir POST isteği gönderilerek birden çok hücreyi düzenleyebilirsiniz. Ö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, sol üst koordinat olarak söz konusu hücreyle başlayarak sayfaya yazılır. Bunun yerine çok hücreli bir aralık belirtirseniz sağladığınız değerler bu aralığa tam olarak sığmalıdır. Aksi takdirde, API hata döndürür.