إذا كانت لديك تطبيقات حالية تستند إلى الإصدار 3 من Google Sheets API، يمكنك نقل البيانات إلى الإصدار 4 من Google Sheets API. يستند الإصدار 4 إلى تنسيق JSON، ويحتوي على واجهة سهلة الاستخدام، ويضيف عددًا كبيرًا من الوظائف غير المتاحة في الإصدار 3.
توفّر هذه الصفحة تعيينًا بين أوامر الإصدار القديم من Sheets API v3 وعملياته المعادلة في الإصدار 4 من Sheets API. تركّز عملية الربط إلى حدٍ كبير على مجموعة spreadsheets.values التي توفّر وظيفة قراءة وكتابة الخلايا مباشرةً. تعالج مجموعة جداول البيانات الجوانب الأخرى، مثل إضافة أوراق بيانات أو تعديل خصائصها. يُرجى العلم أنّ بنى JSON في الإصدار 4 من واجهة برمجة التطبيقات غير متوافقة مع بنى XML المستخدَمة في الإصدار 3.
لمزيد من المعلومات عن المراجع المتاحة في واجهة برمجة التطبيقات Sheets v4 API، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.
الرموز والمصطلحات
تشير v3 API إلى الأوراق ضمن جدول بيانات معيّن باسم "أوراق البيانات". وهذا مصطلح مرادف لعبارة "جداول البيانات" التي تستخدمها واجهة برمجة التطبيقات في الإصدار 4.
غالبًا ما تطلب منك واجهات برمجة التطبيقات تحديد رقم تعريف جدول البيانات الذي تعمل عليه. وغالبًا ما تتطلّب هذه الإجراءات أيضًا معرّف جدول البيانات الذي يتم التلاعب به. تظهر هذه القيم إما كجزء من عنوان URL لنقطة نهاية واجهة برمجة التطبيقات أو كمَعلمات طلب بحث أو كجزء من نص الطلب. في هذه الصفحة، تشير العنصران النائبان spreadsheetId وsheetId إلى معرّفَي جدول البيانات وورقة البيانات، على التوالي. عند استخدام الطرق описан في هذه الصفحة، استبدِل الأرقام التعريفية الفعلية في هذه المواقع الجغرافية.
تُحدِّد واجهة برمجة التطبيقات v3 أيضًا رقم تعريف للصفوف التي يتم استرجاعها باستخدام خلاصة القائمة، ويُمثّل ذلك في هذه الصفحة العنصر النائب rowId.
السماح بالطلبات
عند تشغيل تطبيقك، يطلب من المستخدمين منح أذونات معيّنة، وتحديد النطاقات التي تحدّد الأذونات التي يطلبها التطبيق.
واجهة برمجة التطبيقات v3
تعمل الإصدار 3 من واجهة برمجة التطبيقات Sheets API باستخدام نطاق تفويض واحد:
https://spreadsheets.google.com/feeds
وهو عنوان بديل لـ
https://www.googleapis.com/auth/spreadsheets
يمكن استخدام أيّ من تنسيقَي النطاق.
واجهة برمجة التطبيقات v4
تستخدم الإصدار 4 من واجهة برمجة التطبيقات Sheets API واحدة أو أكثر من المجموعة التالية من النطاقات:
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
استخدِم النطاقات للقراءة فقط إذا لم يكن تطبيقك بحاجة إلى إجراء تعديلات على جداول بيانات المستخدم أو خصائصها. استخدِم نطاقات جداول البيانات بدلاً من نطاقات Drive إذا لم يكن التطبيق بحاجة إلى إذن وصول عام إلى Drive.
مستوى الرؤية
في الإصدارات القديمة من واجهة برمجة التطبيقات، يُستخدَم مصطلح مستوى العرض للإشارة إلى مدى توفّر جدول بيانات معيّن.
واجهة برمجة التطبيقات v3
تُعبّر الإصدار 3 من واجهة برمجة التطبيقات Sheets API عن مستوى العرض مباشرةً في نقاط النهاية. تم "نشر جدول بيانات public" على الويب، وبالتالي يمكن للواجهة برمجة التطبيقات
الوصول إليه بدون إذن، في حين أنّ جدول بيانات private يتطلّب
المصادقة. يتم تحديد مستوى العرض في نقطة النهاية بعد
رقم تعريف جدول البيانات:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
واجهة برمجة التطبيقات v4
في الإصدار 4 الجديد من Sheets API، لا يتوفّر بيان صريح عن مستوى العرض. يتم إجراء طلبات البيانات من واجهة برمجة التطبيقات باستخدام أرقام تعريف جداول البيانات. إذا لم يكن لدى التطبيق إذن بالوصول إلى جدول البيانات المحدّد، يتم عرض رسالة خطأ. وإلا، تتم مواصلة المكالمة.
الإسقاط
يستخدم الإصدار 3 من واجهة برمجة التطبيقات Sheets API مصطلح الإسقاط للإشارة إلى مجموعة البيانات التي يتم عرضها من خلال طلب معيّن لواجهة برمجة التطبيقات، سواء كانت المجموعة بأكملها أو مجموعة فرعية ثابتة محدّدة ضمن واجهة برمجة التطبيقات. لا يستخدم الإصدار 4 من واجهة برمجة التطبيقات Sheets API الإسقاط، بل يتيح لك التحكّم بشكل أكبر في البيانات التي يتم عرضها.
واجهة برمجة التطبيقات v3
لا يتوفّر سوى إعدادان محتملان للعرض في الإصدار 3 من واجهة برمجة التطبيقات Sheets API. تُعرِض full
التصنيف جميع المعلومات المتاحة، في حين تعرِض basic
مجموعة فرعية أصغر وثابتة من البيانات (لخلاصات جداول البيانات والقوائم والخلايا).
مثل مستوى العرض، يجب تحديد الإسقاط في نقطة نهاية واجهة برمجة التطبيقات
(بعد إعداد مستوى العرض):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
إنّ المجموعة الفرعية الأصغر من البيانات التي يوفّرها إسقاط basic قيّمة
لتحسين كفاءة الرمز، ولكن لا يمكن تخصيصها.
واجهة برمجة التطبيقات v4
على الرغم من أنّ الإصدار 4 من واجهة برمجة التطبيقات Sheets API يمكنه عرض مجموعة بيانات كاملة، إلا أنّه لا يحدّد مجموعات فرعية ثابتة مشابهة لإعداد مستوى الرؤية basic في الإصدار 3 من واجهة برمجة التطبيقات Sheets API.
تحدّد الطرق في مجموعة جدول البيانات
كمية البيانات التي تعرضها من خلال استخدام
مَعلمة طلب بحث الحقول.
على سبيل المثال، يعرِض طلب البحث التالي عناوين جميع ملفّات البيانات في جدول بيانات معيّن فقط:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
إنشاء جدول بيانات
واجهة برمجة التطبيقات v3
لا توفّر الإصدار 3 من واجهة برمجة التطبيقات Sheets API وسيلة لإنشاء جداول بيانات جديدة،
وبدلاً من ذلك، يمكن استخدام الطريقة Drive API Files.create
لإنشاء ملفات جداول بيانات جديدة. يتطلب ذلك من
التطبيق الإفصاح عن نطاق https://www.googleapis.com/auth/drive.
واجهة برمجة التطبيقات v4
يمكن استخدام الطريقة Drive API Files.create
أيضًا مع الإصدار 4 من واجهة برمجة التطبيقات Sheets API، ولكنّها تتطلّب من التطبيق توفير
نطاق https://www.googleapis.com/auth/drive.
كبديل مكافئ، توفّر الإصدار 4 من واجهة برمجة التطبيقات Sheets API الإجراء spreadsheets.create ، والذي يمكنه أيضًا إضافة جداول بيانات اختياريًا وضبط خصائص جدول البيانات والجدول، وإضافة نطاقات مُسمّاة. على سبيل المثال، ينشئ الإجراء التالي جدول بيانات جديدًا ويُطلق عليه اسم "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}قوائم جداول البيانات للمستخدم الذي تمّت المصادقة عليه
واجهة برمجة التطبيقات v3
تسمح خلاصة Sheets API v3 للتطبيق باسترداد قائمة بكل جداول البيانات التي يمكن للمستخدم المُعتمَد الوصول إليها. نقطة نهاية خلاصة جدول البيانات هي:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
واجهة برمجة التطبيقات v4
لا توفّر واجهة برمجة التطبيقات Sheets API v4 هذه العملية المحدّدة. ننصحك بنقل بيانات تطبيقك لاستخدام نطاق drive.file مع أداة Google Picker لاختيار جداول البيانات.
في الحالات التي يكون فيها إدراج جداول البيانات مطلوبًا، يمكن تكراره
من خلال طريقة Drive API Files.list، باستخدام
طلب بحث mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'يتطلّب استخدام طريقة files.list في Drive API لعرض كل جداول بيانات المستخدم نطاقًا محدودًا.
استرداد البيانات الوصفية للورقة
توفّر الإصدار 3 من واجهة برمجة التطبيقات Sheets API خلاصة للوصول إلى البيانات الوصفية للورقة التي يتم تضمينها في جدول بيانات معيّن (يتم الوصول إلى بيانات الصفوف والخلايا من خلال خلاصة منفصلة). تتضمّن البيانات الوصفية معلومات مثل عناوين جداول البيانات ومقاييس حجمها.
توفّر الطريقة spreadsheets.get في Sheets API v4 إمكانية الوصول إلى هذه المعلومات وغير ذلك الكثير.
واجهة برمجة التطبيقات v3
يمكن الوصول إلى خلاصة ورقة البيانات من نقطة نهاية واجهة برمجة التطبيقات هذه (باستخدام رأس تفويض مناسب):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
تتضمّن الاستجابة لهذا الطلب بنية مشابهة لهذه، مع تضمين data
لكل ورقة في <entry> منفصل:
<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
يمكن استخدام الطريقة spreadsheets.get
للحصول على سمات جدول البيانات والبيانات الوصفية الأخرى، وهي
أكثر بكثير مما هو متاح باستخدام الإصدار 3 من واجهة برمجة التطبيقات Sheets API. إذا كنت تريد قراءة خصائص الورقة فقط، اضبط المَعلمة includeGridData
للطلب على false لمنع تضمين بيانات خلايا جدول البيانات:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
يحتوي استجابة Spreadsheet
على صفيف من عناصر Sheet
، ويمكن العثور على عناوين الأوراق ومعلومات الحجم على وجه التحديد
ضمن عنصر SheetProperties
في هذه العناصر. على سبيل المثال:
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}إضافة ورقة بيانات إلى جدول بيانات
تسمح لك كلتا واجهات برمجة التطبيقات بإضافة أوراق بيانات جديدة إلى جدول بيانات حالي.
واجهة برمجة التطبيقات v3
يمكن لواجهة Sheets API v3 إضافة أوراق بيانات جديدة إلى جدول بيانات من خلال إرسال طلب POST التالي (المصادق عليه). يمكنك تحديد حجم
الورقة الجديدة:
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
يمكنك إضافة جداول جديدة من خلال تقديم طلب AddSheet في الطريقة spreadsheets.batchUpdate. كجزء من محتوى الطلب، يمكنك تحديد سمات جدول بيانات الجداول الجديدة، وجميع السمات اختيارية. يُعدّ تقديم عنوان يُستخدَم لجدول بيانات حالي خطأ.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}تغيير عنوان وحجم ورقة البيانات
تتيح لك الإصدار 3 من Sheets API تعديل عناوين جداول البيانات وحجمها، ويسمح الإصدار 4 من Sheets API بهذا أيضًا، ولكن يمكن استخدامه أيضًا لتعديل سمات أخرى للجدول. يُرجى العِلم أنّ تصغير حجم ورقة البيانات قد يؤدي إلى حذف البيانات في الخلايا التي تم اقتصاصها بدون تحذير.
واجهة برمجة التطبيقات v3
لتغيير عنوان ورقة البيانات أو حجمها، ابدأ باسترداد
خلاصة ورقة البيانات و
العثور على إدخال ورقة البيانات المطلوب الذي يحتوي على عنوان URL edit.
عدِّل البيانات الوصفية لجدول البيانات وأرسِلها كنص طلب PUT
إلى عنوان URL المخصّص لتعديل الطلبات. على سبيل المثال:
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
لتعديل الحجم والعنوان وغيرها من سمات ورقة البيانات، قدِّم طلبًا لسمة
updateSheetProperties
في الطريقة
spreadsheets.batchUpdate. يجب أن يتضمّن نص طلب POST السمات التي يجب
تغييرها، ويجب أن تُدرج المَعلمة fields هذه السمات صراحةً
(إذا كنت تريد تعديل جميع السمات، استخدِم fields:"*" كاختصار
لإدراجها كلها). على سبيل المثال، يحدّد ما يلي أنّه يجب تعديل سمتَي عنوان وحجم الورقة لتلك التي تحمل المعرّف المحدّد:
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)"
}
}
],
}لاسترداد sheetId لصفحة، استخدِم طريقة جدول البيانات spreadsheets.get.
حذف ورقة بيانات
يمكن لأي من واجهات برمجة التطبيقات إزالة أوراق بيانات من جدول بيانات معيّن.
واجهة برمجة التطبيقات v3
لحذف ورقة بيانات، ابدأ باسترداد
خلاصة ورقة البيانات، ثم
أرسِل طلب DELETE على عنوان URL edit لإدخال ورقة البيانات المستهدَفة.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
واجهة برمجة التطبيقات v4
لحذف ورقة بيانات، قدِّم طلبًا لسمة
DeleteSheet
في الأسلوب
spreadsheets.batchUpdate. يجب أن يحتوي نص طلب POST على sheetId فقط لحذف جدول البيانات. على سبيل المثال:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}لاسترداد sheetId لصفحة فردية، استخدِم الإجراء spreadsheets.get لجدول البيانات.
استرداد بيانات الصف
خلاصة صفوف القوائم هي إحدى الطريقتَين اللتين توفّرهما Sheets API v3 ل الوصول إلى البيانات داخل خلايا جدول البيانات (الطريقة الأخرى هي خلاصة الخلايا). تهدف خلاصة الصفوف إلى إتاحة عمليات جدول البيانات الشائعة (قراءة الصفوف على حدة، إلحاق الصفوف، والترتيب)، ولكنها تستند إلى افتراضات معيّنة تجعلها غير مناسبة لبعض المهام. على وجه التحديد، تفترض خلاصة القائمة أنّ الصفوف الفارغة هي نهايات الخلاصة، وأنّ العناوين الإلزامية متوفّرة في الصف الأول من جدول البيانات.
في المقابل، لا تستخدم الإصدار 4 من واجهة برمجة التطبيقات Sheets API طرق وصول خاصة بالصفوف. بدلاً من ذلك، يتم الوصول إلى بيانات خلايا الورقة من خلال الإشارة إلى النطاقات الخاصة المطلوبة باستخدام ترميز A1. يمكن أن تكون النطاقات مجموعات من الخلايا أو صفوفًا أو أعمدة أو أوراق بيانات كاملة. يمكن لواجهة برمجة التطبيقات أيضًا الوصول إلى مجموعات غير متصلة من الخلايا.
واجهة برمجة التطبيقات v3
لتحديد عنوان URL لخلاصة مستندة إلى قائمة لجدول بيانات معيّن، استرجع خلاصة جدول البيانات و ابحث عن عنوان URL لخلاصة القائمة في إدخال جدول البيانات الذي يهمّك.
لاسترداد خلاصة مستندة إلى قائمة، أرسِل طلب GET إلى عنوان URL لخلاصة القائمة،
باستخدام رأس تفويض مناسب. على سبيل المثال:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
يحتوي الردّ على هذا الطلب، من بين أمور أخرى، على إدخالات تتوافق مع صفوف محدّدة. تتم الإشارة إلى الخلايا الفردية باستخدام الأسماء المقدَّمة في صف عنوان جدول البيانات (الإلزامي). على سبيل المثال، إليك إدخال سطر واحد:
<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>
يتم تلقائيًا عرض الصفوف المعروضة في خلاصة القائمة بترتيب الصفوف. يوفّر الإصدار 3 من واجهة برمجة التطبيقات Sheets API مَعلمات طلب بحث لتغيير هذا الترتيب.
الترتيب العكسي:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
الترتيب حسب عمود معيّن:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameتسمح أيضًا الإصدار 3 من واجهة برمجة التطبيقات Sheets API بفلترة صفوف معيّنة من خلال طلب بحث منظَّم (يُشار إليه من خلال عناوين الأعمدة):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175واجهة برمجة التطبيقات v4
باستخدام الإصدار 4 من واجهة برمجة التطبيقات Sheets API، يمكن استرداد الصفوف حسب النطاق باستخدام الطريقتَين spreadsheets.values.get أو spreadsheets.values.batchGet. على سبيل المثال، يعرض الإجراء التالي جميع الصفوف في "الجدول1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
يتضمّن الردّ على هذا الطلب بنية مشابهة لما يلي:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}لا يتم تضمين الخلايا الفارغة في نهاية الصفوف أو الأعمدة أو جداول البيانات في الاستجابة عند استرداد الصفوف أو الأعمدة أو جداول البيانات بالكامل.
لا تتضمّن واجهة Sheets API v4 مكافئات لمَعلمات طلب البحث بترتيب الصفوف التي تقدّمها واجهة Sheets API v3. إنّ الترتيب العكسي بسيط، ما عليك سوى
معالجة صفيف values المعروض بالترتيب العكسي. لا يُسمح بالترتيب حسب العمود عند القراءة، ولكن يمكن ترتيب البيانات في ورقة البيانات (باستخدام طلب SortRange) ثم قراءتها.
لا تتوفّر حاليًا في Sheets API v4 طلبات بحث منظَّمة مكافئة مباشرة لطلبات البحث منظَّمة في Sheets API v3. ومع ذلك، يمكنك استرداد البيانات ذات الصلة و ترتيبها حسب الحاجة في تطبيقك.
إضافة صف جديد من البيانات
يمكنك إضافة صف جديد من البيانات إلى جدول باستخدام أيّ من واجهتَي برمجة التطبيقات.
واجهة برمجة التطبيقات v3
لتحديد عنوان URL لخلاصة مستندة إلى قائمة لجدول بيانات معيّن، استرجع خلاصة جدول البيانات و ابحث عن عنوان URL للمشاركة في إدخال جدول البيانات الذي يهمّك.
لإضافة صف من البيانات، أرسِل طلبًا من النوع POST إلى عنوان URL للنشر،
باستخدام عنوان تفويض مناسب. على سبيل المثال:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
يجب أن يحتوي نص طلب POST على إدخال لبيانات الصف التي تريد
إضافتها، مع خلايا فردية تتم الإشارة إليها من خلال عناوين الأعمدة:
<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>
يتم إلحاق الصفوف الجديدة بنهاية ورقة البيانات المحدّدة.
واجهة برمجة التطبيقات v4
باستخدام الإصدار 4 من واجهة برمجة التطبيقات Sheets API، يمكنك إلحاق الصفوف باستخدام الأسلوب spreadsheets.values.append. يكتب المثال التالي صفًا جديدًا من البيانات أسفل الجدول الأخير في "الورقة1" من جدول بيانات.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}بالإضافة إلى ذلك، تتيح لك الإصدار 4 من واجهة برمجة التطبيقات Sheets API أيضًا إلحاق الخلايا بخصائص وتنسيقات محدّدة باستخدام طلبات AppendCells في spreadsheets.batchUpdate.
تعديل صف يحتوي على بيانات جديدة
تسمح كلتا واجهات برمجة التطبيقات بتعديل بيانات الصفوف باستخدام قيم جديدة.
واجهة برمجة التطبيقات v3
لتعديل صف من البيانات، راجِع خلاصة القائمة لتحديد موقع الإدخال للصف الذي تريد تعديله. عدِّل محتويات هذه الإدخالات حسب الحاجة. تأكَّد من أنّ قيمة المعرّف في الإدخال الذي تستخدمه تتماثل تمامًا مع معرّف الإدخال الحالي.
بعد تعديل الإدخال، أرسِل طلبًا إلى PUT يتضمّن الإدخال كجسد طلب إلى عنوان URL edit المقدَّم في إدخال الصف،
باستخدام رأس تفويض مناسب. على سبيل المثال:
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
باستخدام Sheets API v4، يمكنك تعديل صف باستخدام ترميز A1 للصف الذي تريد تعديله وإصدار طلب spreadsheets.values.update لاستبدال هذا الصف. يجب أن يشير النطاق المحدّد فقط إلى الخلية الأولى في الصف، وتستنتج واجهة برمجة التطبيقات الخلايا التي سيتم تعديلها استنادًا إلى القيم المقدَّمة مع الطلب. إذا حدّدت بدلاً من ذلك نطاقًا يتضمّن عدة خلايا، يجب أن تكون القيم التي تقدّمها ضمن هذا النطاق، وإذا لم تكن كذلك، ستعرِض واجهة برمجة التطبيقات خطأً.
في المثال التالي للطلب ونص الطلب، تتم إضافة بيانات إلى الصف الرابع من "الجدول1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}يمكنك أيضًا تعديل بيانات الصفوف من الطريقة spreadsheet.values.batchUpdate ، ويُعدّ استخدام هذه الطريقة أكثر فعالية إذا كنت تُجري تعديلات متعددة على الصفوف أو الخلايا.
بالإضافة إلى ذلك، تتيح لك الإصدار 4 من واجهة برمجة التطبيقات Sheets API أيضًا تعديل سمات الخلايا و تنسيق الخلايا باستخدام طلبات UpdateCells أو RepeatCell في spreadsheets.batchUpdate.
حذف صف
تتيح كلتا واجهتَي برمجة التطبيقات حذف الصفوف. تتم إزالة الصف المحذوف من جدول البيانات، ويتم دفع الصفوف تحته للأعلى بمقدار صف واحد.
واجهة برمجة التطبيقات v3
لحذف صف، عليك أولاً استرداد الصف المراد حذفه من
خلاصة القائمة،
ثم إرسال طلب DELETE إلى عنوان URL edit المقدَّم في إدخال الصف.
هذا هو عنوان URL نفسه المستخدَم لتعديل الصف.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
إذا كنت تريد التأكّد من عدم حذف صف تم تغييره بواسطة مستخدم آخر منذ استرجاعه، أدرِج عنوان HTTP If-Match الذي يحتوي على قيمة علامة ETag للصف الأصلي. يمكنك تحديد قيمة ETag الأصلية للصف من خلال فحص سمة gd:etag لعنصر الإدخال.
إذا أردت حذف الصف بغض النظر عمّا إذا كان مستخدم آخر قد عدّله منذ استرجاعه، استخدِم If-Match: * ولا تُدرِج علامة ETag. (في هذه الحالة، لا تحتاج إلى استرداد الصف قبل حذفه).
واجهة برمجة التطبيقات v4
يتم حذف الصفوف باستخدام Sheets API v4 من خلال طلب الطريقة spreadsheet.batchUpdate ، باستخدام طلب DeleteDimension. يمكن أيضًا استخدام هذا الطلب لإزالة الأعمدة، ويمكن للمطوّرين اختيار إزالة جزء من صف أو عمود فقط. على سبيل المثال، يزيل الإجراء التالي الصف السادس من ورقة البيانات باستخدام المعرّف المحدّد (تستند فهارس الصفوف إلى الصفر، مع تضمين startIndex واستبعاد endIndex):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}يمكن استرداد sheetId لصفحة باستخدام الأسلوب spreadsheet.get.
استرداد بيانات الخلايا
توفّر الإصدار 3 من واجهة برمجة التطبيقات Sheets API خلاصة خلايا للوصول الأساسي إلى جميع البيانات المخزّنة في جدول ملف شخصي. للوصول للقراءة، يمكن أن تقدّم خلاصة الخلايا محتوى جدول البيانات بالكامل
أو نطاقًا من خلايا الجدول المحدّد من خلال مجموعة من مَعلمات طلب البحث،
ولكن فقط كتلة واحدة، ويجب استرجاع النطاقات غير المتّصلة
بشكل منفصل باستخدام طلبات GET إضافية.
يمكن لواجهة برمجة التطبيقات Sheets API 4 استرداد أي مجموعة من بيانات الخلايا من ورقة بيانات (بما في ذلك نطاقات متعددة غير متصلة). لا يمكن لواجهة برمجة التطبيقات Sheets API 3 إلا عرض محتوى الخلايا على هيئة قيم إدخال (على النحو الذي يدخله المستخدم على لوحة المفاتيح) و/أو نتائج الصيغة (إذا كانت رقمية). وتمنح واجهة برمجة التطبيقات Sheets API 4 إذن الوصول الكامل إلى القيم و الصيغ والتنسيق والروابط الفائقة والتحقّق من البيانات وغيرها من السمات.
واجهة برمجة التطبيقات v3
لتحديد عنوان URL لخلاصة مستندة إلى خلية لجدول بيانات معيّن، راجِع خلاصة جدول البيانات وابحث عن عنوان URL لخلاصة الخلية في إدخال جدول البيانات الذي يهمّك.
لاسترداد خلاصة مستندة إلى خلية، أرسِل طلب GET إلى عنوان URL لخلاصة الخلايا،
باستخدام رأس تفويض مناسب. على سبيل المثال:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
تتم الإشارة إلى الخلايا باستخدام رقم الصف والعمود. يمكن جلب قياس واحد محدّد
باستخدام مَعلمات طلب البحث max-row وmin-row وmax-col وmin-col. على سبيل المثال، يسترجع ما يلي جميع الخلايا في العمود
4 (د)، بدءًا من الصف 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4تُعرِض الإصدار 3 من Sheets API inputValue للخلايا التي تم استرجاعها، وهي
القيمة التي كان المستخدم ليكتبها في
واجهة مستخدم "جداول بيانات Google" لإجراء تعديلات على الخلية. يمكن أن يكون inputValue قيمة حرفية
أو صيغة. تعرض واجهة برمجة التطبيقات أحيانًا أيضًا القيمة numericValue، على سبيل المثال،
عندما تؤدي صيغة إلى ظهور رقم. على سبيل المثال، قد يتضمّن الردّ إدخالات خلية
تشبه في تركيبتها ما يلي:
<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
استرداد بيانات الخلايا من خلال استدعاء spreadsheets.values.get أو spreadsheets.values.batchGet للنطاق أو النطاقات التي تهمّك، على التوالي على سبيل المثال، يعرض الإجراء التالي الخلايا في العمود D من "الورقة2"، بدءًا من الصف 2، بالترتيب حسب العمود ويعرض المعادلات كما تم إدخالها (يتم حذف الخلايا الفارغة اللاحقة):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
يتشابه الردّ على هذا الطلب من حيث البنية مع:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}من الأفضل استخدام spreadsheet.values.batchGet إذا كنت تنوي استرداد نطاقات متعددة من بيانات الخلايا. إذا كنت تريد الوصول إلى خصائص الخلية، مثل التنسيق، يجب استخدام الوسيطة spreadsheet.get.
تعديل خلية
تتيح لك الإصدار 3 من Sheets API تعديل محتوى الخلية من خلال إصدار الأمر PUT ل
خلاصة الخلية مع إدخال الخلية المعدَّلة كنص الطلب.
في المقابل، توفّر الإصدار 4 من واجهة برمجة التطبيقات Sheets API الطريقتَين spreadsheets.values.update و spreadsheets.values.batchUpdate لتغيير محتوى الخلية.
واجهة برمجة التطبيقات v3
لتعديل محتوى خلية واحدة، ابحث أولاً عن إدخال الخلية في
خلاصة الخلايا.
يحتوي الإدخال على عنوان URL لتعديل المحتوى. عدِّل الإدخال ليعكس المحتوى الذي تريد أن تظهره الخلية، ثم أرسِل طلبًا من النوع PUT إلى عنوان URL الخاص بتعديل ملف البيانات
مع إدخال الخلية المعدَّل كنص الطلب. على سبيل المثال، يؤدي الإجراء التالي إلى تعديل الخلية D2 (R2C4) لتتضمّن صيغة SUM:
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
يمكن إجراء تعديل خلية واحدة في Sheets API v4 باستخدام الأسلوب
spreadsheets.values.update. تتطلّب هذه الطريقة مَعلمة طلب ValueInputOption، والتي تحدد ما إذا كان سيتم التعامل مع بيانات الإدخال كما لو تم إدخالها في واجهة مستخدم "جداول بيانات Google" (USER_ENTERED)، أو تركها بدون تحليل واستخدامها كما هي (RAW). على سبيل المثال، تعدّل العبارة التالية الخلية D2 باستخدام صيغة:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}إذا كنت بصدد إجراء تعديلات على عدة خلايا، استخدِم الأسلوب spreadsheets.values.batchUpdate لإصدارها في طلب واحد.
تعديل عدّة خلايا من خلال طلب مجمّع
توفّر كلتا واجهات برمجة التطبيقات وسيلة لإجراء تغييرات على محتوى خلايا متعددة باستخدام طلب واحد (مجموعة). ليس مطلوبًا أن تكون الخلايا التي يشير إليها طلب الحزمة في نطاق متّصل.
في حال تعذّر إجراء تعديل واحد أو أكثر من تعديلات الخلايا في الحزمة، تسمح واجهة Sheets API v3 بنجاح التعديلات الأخرى. ومع ذلك، تُعرِض واجهة برمجة التطبيقات Sheets API v4 خطأ إذا تعذّر إجراء أيّ من التعديلات المجمّعة، ولا تطبّق أيًّا منها في هذه الحالة.
واجهة برمجة التطبيقات v3
لتعديل عدة خلايا، استرد أولاً خلاصة خلية
لجدول البيانات. يحتوي الإدخال على عنوان URL لمجموعة. أرسِل POST
طلبًا إلى عنوان URL هذا، مع نص طلب يصف الخلايا التي تريد تعديلها ومحتوى الخلية الجديد. يتضمّن طلب POST ونص الطلب
بنية مشابهة لما يلي:
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 الطلب بشكل فريد ضمن الحزمة.
يجب أن يكون الحقل batch:operation هو update لتعديلات الخلايا. gs:cell
تُحدِّد الخلية حسب رقم الصف والعمود وتوفِّر البيانات الجديدة
لإدراجها هناك. يحتوي id على عنوان URL الكامل للخلية التي سيتم تعديلها.
يجب أن تحتوي link على سمة href تحتوي على المسار الكامل إلى
رقم تعريف الخلية. يجب إدخال قيم في جميع هذه الحقول لكل إدخال.
واجهة برمجة التطبيقات v4
توفّر الإصدار 4 من واجهة برمجة التطبيقات Sheets API ميزة التعديل المجمّع لقيم الخلايا من خلال الوسيطة spreadsheets.values.batchUpdate.
يمكن تعديل عدة خلايا من خلال إرسال طلب POST يتضمّن
تغييرات البيانات المحدّدة في نص الطلب. على سبيل المثال:
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"]]
}
]
}إذا حدّدت خلية واحدة كنطاق، تتم كتابة كل القيم المقدَّمة في ورقة البيانات بدءًا من تلك الخلية بصفتها الإحداثي الأيمن العلوي. إذا حدّدت بدلاً من ذلك نطاقًا يتضمّن عدة خلايا، يجب أن تلائم القيم التي تقدّمها هذا النطاق تمامًا، وإذا لم يكن الأمر كذلك، ستعرض واجهة برمجة التطبيقات رسالة خطأ.