إذا كانت لديك تطبيقات حالية تستند إلى الإصدار 3 من Google Sheets API، يمكنك نقل البيانات إلى Google Sheets API v4. يعتمد الإصدار 4 من اللعبة على JSON، وهو أسهل في الاستخدام ويضيف قدرًا كبيرًا من الوظائف غير الممكنة في الإصدار 3.
توفر هذه الصفحة عملية ربط بين أوامر الإصدار 3 من Sheets API القديمة و عمليات مماثلة في الإصدار 4 من Sheets API. يركز التعيين بشكل كبير على spreadsheets.values التي توفر وظيفة القراءة والكتابة المباشرة للخلية. أمّا الجوانب الأخرى، مثل إضافة أوراق البيانات أو تعديل خصائص الورقة، فهي مجموعة جداول البيانات. يُرجى العلم أنّ بُنى JSON الخاصة بواجهة برمجة التطبيقات v4 لا تتوافق مع الأنظمة القديمة بُنى XML المستخدمة في الإصدار 3.
لمزيد من المعلومات حول الموارد المتوفرة في Sheets v4 API، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.
الترميز والمصطلحات
تشير واجهة برمجة التطبيقات v3 إلى الأوراق داخل جدول بيانات معيّن باسم "أوراق العمل". هذا مرادف لمصطلح "sheets" التي تستخدمها واجهة برمجة التطبيقات v4.
غالبًا ما تتطلّب منك واجهات برمجة التطبيقات تحديد رقم تعريف جدول بيانات. جدول البيانات الذي تعمل عليه. كما أنها تتطلب غالبًا معرف الورقة التي يتم التلاعب بها. تظهر هذه القيم إما كجزء من نقطة نهاية واجهة برمجة التطبيقات عنوان URL، أو كمعلَمات طلب بحث، أو كجزء من نص الطلب. في هذه الصفحة، العنصران النائبان spreadsheetId وsheetId يشيران إلى معرفات جداول البيانات والأوراق، على التوالي. عند استخدام الطرق الموضحة في هذه الصفحة، تحل محل الأرقام التعريفية الفعلية في هذه المواقع.
تُعيِّن v3 API أيضًا معرّفًا للصفوف التي تم استردادها باستخدام list feed، يتم تمثيل ذلك في هذه الصفحة من خلال العنصر النائب rowId.
السماح بالطلبات
عند تشغيل تطبيقك، يطلب من المستخدمين منح أذونات معيّنة. النطاقات التي التي تحددها في التطبيق تحدد الأذونات التي يطلبها.
الإصدار 3 من واجهة برمجة التطبيقات
يعمل الإصدار 3 من Sheets API باستخدام نطاق تفويض واحد:
https://spreadsheets.google.com/feeds
وهو اسم مستعار
https://www.googleapis.com/auth/spreadsheets
يمكن استخدام تنسيق أي نطاق.
الإصدار 4 من واجهة برمجة التطبيقات
يستخدم الإصدار 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.
مستوى الرؤية
في الإصدارات القديمة من واجهة برمجة التطبيقات، يُستخدم مصطلح visibility للإشارة إلى ومدى توفر جدول بيانات معين.
الإصدار 3 من واجهة برمجة التطبيقات
يعبّر الإصدار الثالث من Sheets API عن إذن الوصول مباشرةً في نقاط النهاية. public
تم "نشر جدول البيانات على الويب" وبالتالي يمكن الوصول إليه عن طريق
واجهة برمجة التطبيقات بدون إذن، بينما لا يتطلب جدول بيانات private
المصادقة. ويتم تحديد مستوى الرؤية في نقطة النهاية بعد
معرف جدول البيانات:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
الإصدار 4 من واجهة برمجة التطبيقات
في الإصدار 4 من Sheets API الجديد، لم يتم تقديم بيان صريح بشأن إذن الوصول. يتم إجراء طلبات البيانات من واجهة برمجة التطبيقات باستخدام معرّفات جداول البيانات. وإذا كان التطبيق لا يحتوي على إذن للوصول إلى جدول البيانات المحدد، تم عرض خطأ. أو تستمر المكالمة.
الإسقاط
يتم استخدام مصطلح الإسقاط من خلال الإصدار 3 من Sheets API للإشارة إلى مجموعة البيانات يعرضها طلب بيانات من واجهة برمجة التطبيقات، سواء كان بأكمله أو مجموعة فرعية ثابتة المحددة داخل واجهة برمجة التطبيقات. لا يستخدم الإصدار 4 من Sheets API ميزة الإسقاط. بالأحرى، يسمح لك بمزيد من التحكم في البيانات التي يتم إرجاعها.
الإصدار 3 من واجهة برمجة التطبيقات
لا يوجد سوى إعدادين محتملين للعرض في الإصدار 3 من Sheets API. full
يُرجع الإسقاط جميع المعلومات المتاحة، بينما تعرض basic
مجموعة فرعية أصغر وثابتة من البيانات (لخلاصات أوراق العمل والقوائم والخلايا).
يجب تحديد التوقعات في نقطة نهاية واجهة برمجة التطبيقات، تمامًا مثل مستوى الرؤية
(بعد إعداد مستوى الرؤية):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
إنّ المجموعة الفرعية الأصغر من البيانات التي يوفّرها توقع "basic
" ذات قيمة.
لجعل الرمز البرمجي أكثر كفاءة، ولكن لا يمكن تخصيصه
الإصدار 4 من واجهة برمجة التطبيقات
بينما يمكن للإصدار 4 من Sheets API عرض مجموعة بيانات كاملة، فإنه لا يحدد مجموعة بيانات ثابتة
مجموعات فرعية مشابهة لإعداد إذن الوصول basic
، في الإصدار 3 من Sheets API.
الطرق الواردة في جدول البيانات
جمع البيانات تقييد كمية البيانات التي يقومون بإرجاعها من خلال استخدام
معلَمة طلب بحث الحقول
على سبيل المثال، يُرجع الاستعلام التالي فقط عناوين جميع والأوراق في جدول بيانات معين:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
إنشاء جدول بيانات
الإصدار 3 من واجهة برمجة التطبيقات
لا يوفّر الإصدار 3 من Sheets API وسيلة لإنشاء جداول بيانات جديدة.
بدلاً من ذلك، يمكنك استخدام Drive API Files.create
كيفية استخدامها لإنشاء ملفات جداول بيانات جديدة. يتطلب هذا
للإعلان عن نطاق https://www.googleapis.com/auth/drive
.
الإصدار 4 من واجهة برمجة التطبيقات
يمكنك استخدام طريقة 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"} }
سرد جداول البيانات للمستخدم الذي تمت مصادقته
الإصدار 3 من واجهة برمجة التطبيقات
تسمح خلاصة الإصدار 3 من Sheets API للتطبيق باسترداد قائمة بجميع إلى جداول البيانات يمكن الوصول إليها من قبل المستخدم الذي تمت مصادقته. خلاصة جدول البيانات نقطة النهاية هي:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
الإصدار 4 من واجهة برمجة التطبيقات
لا يوفّر الإصدار 4 من Sheets API هذه العملية المحدّدة. ننصحك بما يلي: نقل تطبيقك لاستخدام نطاق drive.file إلى جانب أداة اختيار Google لاختيار جداول البيانات.
في الحالات التي تكون فيها جداول البيانات مطلوبة، يمكن نسخها
عبر الطريقة 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 خلاصة للوصول إلى البيانات الوصفية لورقة البيانات. الواردة في جدول بيانات معين (يتم الوصول إلى بيانات الصف والخلية من خلال خلاصة منفصلة). تتضمن بيانات التعريف معلومات مثل عناوين الأوراق معلومات المقاس.
الإصدار 4 من Sheets API spreadsheets.get الوصول إلى هذه المعلومات، وغير ذلك الكثير.
الإصدار 3 من واجهة برمجة التطبيقات
يمكن الوصول إلى خلاصة ورقة العمل من نقطة نهاية واجهة برمجة التطبيقات هذه (باستخدام عنوان التفويض المناسب):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
الرد على هذا الطلب له بنية مشابهة لهذه،
تضمين بيانات كل ورقة بيانات في <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>
الإصدار 4 من واجهة برمجة التطبيقات
ملف 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 }, ... }, ... }, ... ], ... }
إضافة ورقة إلى جدول بيانات
تتيح لك كلتا واجهتي برمجة التطبيقات إضافة أوراق جديدة إلى جدول بيانات حالي.
الإصدار 3 من واجهة برمجة التطبيقات
يمكن للإصدار 3 من Sheets API إضافة أوراق بيانات جديدة إلى جدول بيانات عن طريق
طلب 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>
الإصدار 4 من واجهة برمجة التطبيقات
يمكنك إضافة أوراق جديدة عن طريق إنشاء 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 تسمح بذلك أيضًا، ولكن يمكن استخدامها أيضًا لتعديل خصائص الورقة الأخرى. لاحظ أن تقليل حجم الورقة قد يؤدي إلى أن تكون البيانات في الخلايا التي تم اقتصاصها سيتم حذفها دون تحذير.
الإصدار 3 من واجهة برمجة التطبيقات
لتغيير عنوان أو حجم ورقة العمل، ابدأ باسترداد
خلاصة ورقة العمل
العثور على إدخال ورقة العمل المطلوب، والذي يحتوي على عنوان 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>
الإصدار 4 من واجهة برمجة التطبيقات
لتعديل الحجم والعنوان وخصائص أخرى مرتبطة بالورقة، يمكنك إنشاء
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.
حذف جدول بيانات
ويمكن لأيّ من واجهة برمجة التطبيقات إزالة أوراق من جدول بيانات معيَّن.
الإصدار 3 من واجهة برمجة التطبيقات
لحذف ورقة عمل، ابدأ باسترداد
خلاصة ورقة العمل، ثم
أرسِل طلب DELETE
على عنوان URL الخاص بـ edit
لإدخال ورقة العمل الهدف.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
الإصدار 4 من واجهة برمجة التطبيقات
لحذف ورقة، أنشئ
DeleteSheet
في
spreadsheets.batchUpdate
. يجب أن يحتوي نص طلب POST
فقط على sheetId
ورقة البيانات المراد حذفها. على سبيل المثال:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteSheet": { "sheetId": sheetId } } ], }
لاسترداد sheetId لورقة فردية، استخدِم السمة جدول بيانات spreadsheets.get .
استرداد بيانات الصف
خلاصة صفوف القوائم هي إحدى الطريقتين اللتين يوفرهما الإصدار 3 من Sheets API الوصول إلى البيانات داخل خلايا جدول بيانات (وآخر هو خلاصة الخلايا). تشير رسالة الأشكال البيانية تهدف خلاصة الصفوف إلى دعم عمليات جداول البيانات الشائعة (قراءة صف تلو الآخر، إلحاق الصفوف والفرز)، ولكن يضع افتراضات معينة تجعله غير مناسب لبعض المهام. وعلى وجه التحديد، تفترض خلاصة القائمة أنّ الصفوف الفارغة هي خلاصة عمليات الإغلاق، وأن الرؤوس الإلزامية موجودة في الصف الأول من ورقة البيانات.
في المقابل، لا يستخدم الإصدار 4 من Sheets API طرق وصول الخاصة بصف معين. بدلاً من ذلك، يتم الوصول إلى بيانات خلية ورقة البيانات من خلال الإشارة إلى النطاقات المطلوبة باستخدام تدوين A1. تشير رسالة الأشكال البيانية يمكن أن تكون النطاقات عبارة عن كتل من الخلايا أو صفوف كاملة أو أعمدة كاملة أو أوراق كاملة. يمكن لواجهة برمجة التطبيقات أيضًا الوصول إلى مجموعات منفصلة من الخلايا.
الإصدار 3 من واجهة برمجة التطبيقات
لتحديد عنوان 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
الإصدار 4 من واجهة برمجة التطبيقات
من خلال الإصدار 4 من Sheets API، يمكن استرداد الصفوف حسب النطاق باستخدام spreadsheets.values.get أو spreadsheets.values.batchGet الطرق. على سبيل المثال، يُرجع ما يلي جميع الصفوف في "Sheet1":
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"]] }
لا يتم تضمين الخلايا الفارغة اللاحقة في الرد عند استرداد بالكامل الصفوف أو الأعمدة أو الأوراق.
عدم احتواء الإصدار 4 من Sheets API على مكافئات لطلب البحث بالصف
المعلَمات التي يوفرها الإصدار 3 من Sheets API. الترتيب العكسي بسيط؛ ببساطة
معالجة مصفوفة values
المعروضة بترتيب عكسي. الترتيب حسب العمود غير
متوافقة مع القراءات، ولكن من الممكن فرز البيانات في الورقة (باستخدام
SortRange)
في المشروع ثم قراءته.
لا يتوفّر حاليًا الإصدار 4 من Sheets API مكافئ مباشر لطلبات البحث المنظَّمة للإصدار الثالث من Sheets API. ومع ذلك، يمكنك استرداد البيانات وفرزها حسب الحاجة في طلبك.
إضافة صف جديد من البيانات
يمكنك إضافة صف جديد من البيانات إلى جدول بيانات باستخدام أيّ من واجهة برمجة التطبيقات.
الإصدار 3 من واجهة برمجة التطبيقات
لتحديد عنوان 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>
يتم إلحاق الصفوف الجديدة بنهاية الورقة المحددة.
الإصدار 4 من واجهة برمجة التطبيقات
باستخدام الإصدار 4 من Sheets API، يمكنك إلحاق الصفوف باستخدام spreadsheets.values.append . يكتب المثال التالي صفًا جديدًا من البيانات أسفل آخر جدول في "Sheet1" لجدول بيانات.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
بالإضافة إلى ذلك، يتيح لك الإصدار 4 من Sheets API أيضًا إلحاق خلايا بخلايا الخصائص والتنسيق باستخدام AppendCells الطلبات في spreadsheets.batchUpdate.
تعديل صف يحتوي على بيانات جديدة
تتيح كلتا واجهتَي برمجة التطبيقات تعديل بيانات الصفوف بقيم جديدة.
الإصدار 3 من واجهة برمجة التطبيقات
لتعديل صف من البيانات، راجِع خلاصة القائمة. لتحديد مكان إدخال الصف الذي تريد تعديله. تحديث محتويات هذا الإدخال حسب الحاجة. تأكد من أن قيمة المعرّف في الإدخال التي تستخدمها بالضبط يطابق معرف الإدخال الحالي.
بعد تعديل الإدخال، أرسِل طلب 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>
الإصدار 4 من واجهة برمجة التطبيقات
باستخدام الإصدار 4 من Sheets API، يمكنك تعديل صف باستخدام علامة A1 للصف الذي تريد تعديل وإصدار spreadsheets.values.update أن تطلب استبدال هذا الصف. ينبغي أن يشير النطاق المحدد فقط إلى الخلية الأولى في الصف؛ تستنتج واجهة برمجة التطبيقات الخلايا ليتم تحديثها بناءً على والقيم المقدمة مع الطلب. إذا حددت بدلاً من ذلك نطاقًا متعدد الخلايا، يجب أن تندرج القيم التي تقدمها ضمن هذا النطاق؛ وإلا تعرض واجهة برمجة التطبيقات خطأ.
يضيف المثال التالي نص الطلب ونص الطلب بيانات إلى الصف الرابع من "Sheet1":
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.
حذف صف
تتيح كلتا واجهتَي برمجة التطبيقات حذف الصفوف. تتم إزالة صف محذوف من وجدول البيانات والصفوف أسفله يتم رفعها بمقدار واحد.
الإصدار 3 من واجهة برمجة التطبيقات
لحذف صف، قم أولاً باسترداد الصف المراد حذفه من
قائمة الخلاصة،
بعد ذلك، أرسِل طلب 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. (في هذه الحالة، لا تحتاج إلى استرداد الصف قبل حذفه.)
الإصدار 4 من واجهة برمجة التطبيقات
يتم التعامل مع حذف الصفوف باستخدام الإصدار 4 من Sheets API من خلال 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
إضافية.
يمكن للإصدار 4 من Sheets API استرداد أي مجموعة من بيانات الخلية من ورقة بيانات (بما في ذلك نطاقات منفصلة متعددة). يمكن للإصدار 3 من Sheets API عرض محتوى الخلية فقط كـ قيم الإدخال (كما قد يُدخلها المستخدم بلوحة المفاتيح) و/أو مخرجات معادلة (إذا كانت رقمية) يمنح الإصدار 4 من Sheets API إمكانية الوصول الكامل إلى القيم، والمعادلات والتنسيق والارتباطات التشعبية والتحقق من صحة البيانات والخصائص الأخرى.
الإصدار 3 من واجهة برمجة التطبيقات
لتحديد عنوان URL لخلاصة مستندة إلى خلية خاصة بورقة عمل معينة، تحقق من خلاصة ورقة العمل والعثور على عنوان URL لخلاصة الخلية في إدخال ورقة العمل محل الاهتمام.
لاسترداد خلاصة مستندة إلى خلية، أرسِل طلب GET
إلى عنوان URL لخلاصة الخلية.
باستخدام عنوان تفويض مناسب. على سبيل المثال:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
تتم الإشارة إلى الخلايا باستخدام رقم الصف والعمود. جارٍ جلب عنصر واحد محدد
يمكن إجراء نطاق باستخدام max-row
وmin-row
وmax-col
وmin-col
مَعلمات طلب البحث. على سبيل المثال، ما يلي يسترد جميع الخلايا في العمود
4 (D)، بدءًا من الصف 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>
الإصدار 4 من واجهة برمجة التطبيقات
استرداد بيانات الخلية عن طريق استدعاء spreadsheets.values.get أو spreadsheets.values.batchGet للنطاق أو النطاقات المعنية، على التوالي. على سبيل المثال، بعد ذلك يُرجع الخلايا في العمود D من "Sheet2"، بدءًا من الصف 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 طرق لتغيير محتوى الخلية.
الإصدار 3 من واجهة برمجة التطبيقات
لتعديل محتوى خلية واحدة، ابحث أولاً عن إدخال الخلية في
خلاصة الخلية.
يحتوي الإدخال على عنوان 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>
الإصدار 4 من واجهة برمجة التطبيقات
يمكن تعديل خلية واحدة في الإصدار 4 من Sheets API باستخدام
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 لإصدارها في طلب واحد.
تعديل خلايا متعددة باستخدام طلب مجمّع
توفر كلتا واجهتي برمجة التطبيقات وسيلة لإجراء تغييرات على محتوى خلايا متعددة بطلب واحد (دفعة). الخلايا المشار إليها بواسطة طلب مجمّع هي لا يلزم أن يكون في نطاق طارئ.
في حال تعذّر تعديل الخلايا في الدُفعة أو أكثر، يسمح الإصدار 3 من Sheets API للآخرين بالنجاح. مع ذلك، يعرض الإصدار 4 من Sheets API رسالة خطأ. إذا أخفق أي من التحديثات المجمّعة، ولا يطبق أيًا منها في هذه الحالة.
الإصدار 3 من واجهة برمجة التطبيقات
لتعديل خلايا متعددة، عليك أولاً استرداد خلاصة خلية.
لورقة العمل. يحتوي الإدخال على عنوان 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
التي تحتوي على المسار الكامل إلى
معرف الخلية. جميع هذه الحقول مطلوبة لكل إدخال.
الإصدار 4 من واجهة برمجة التطبيقات
يوفر الإصدار 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"]] } ] }
إذا حددت خلية واحدة كنطاق، فسيتم التعامل مع جميع القيم المقدمة مكتوبة إلى الورقة بدءًا من تلك الخلية كالإحداثي العلوي الأيسر. إذا حددت بدلاً من ذلك نطاقًا متعدد الخلايا، فيجب أن تتناسب القيم التي تقدمها هذا النطاق بالضبط؛ وإلا تعرض واجهة برمجة التطبيقات خطأً.