تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الترحيل من الإصدار الثالث من واجهة برمجة تطبيقات جداول البيانات

إذا كانت لديك تطبيقات حالية تستند إلى الإصدار 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"]]
       }
  ]
}

إذا حددت خلية واحدة كنطاق، فسيتم التعامل مع جميع القيم المقدمة مكتوبة إلى الورقة بدءًا من تلك الخلية كالإحداثي العلوي الأيسر. إذا حددت بدلاً من ذلك نطاقًا متعدد الخلايا، فيجب أن تتناسب القيم التي تقدمها هذا النطاق بالضبط؛ وإلا تعرض واجهة برمجة التطبيقات خطأً.