عمليات البيانات

تتيح لك واجهة Google Sheets API معالجة البيانات داخل جداول البيانات بطرق مختلفة. يمكنك تنفيذ معظم الوظائف المتاحة للمستخدمين الذين يعملون باستخدام واجهة مستخدم "جداول بيانات Google" باستخدام واجهة Sheets API أيضًا. توضّح الأمثلة في هذه الصفحة كيفية تنفيذ بعض عمليات جداول البيانات الشائعة باستخدام واجهة Sheets API.

يتم عرض هذه الأمثلة في شكل طلبات HTTP لتكون محايدة للغة. للتعرّف على كيفية تنفيذ عملية تعديل مجمّع بلغات مختلفة باستخدام مكتبات عملاء Google API، يمكنك الاطّلاع على مقالة تعديل جداول البيانات.

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي ستُدخل فيه أرقام التعريف هذه. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL الخاص به. يمكنك الحصول على رقم تعريف ورقة البيانات باستخدام طريقة spreadsheets.get. يتم تحديد النطاقات باستخدام علامات A1. مثال على نطاق: Sheet1!A1:D5.

تطبيق ميزة التحقّق من صحة البيانات على نطاق

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام SetDataValidationRequest لتطبيق قاعدة التحقّق من صحة البيانات، حيث "القيمة > 5"، على كل خلية في النطاق A1:D10.

يظهر أدناه بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

نسخ تنسيق الخلية ولصقه

توضح عينة التعليمات البرمجية التالية spreadsheets.batchUpdate كيفية استخدام CopyPasteRequest لنسخ التنسيق فقط في النطاق A1:D10 ولصقه في النطاق F1:I10 في ورقة البيانات نفسها. تستخدم الطريقة الـ PasteType تعداد مع PASTE_FORMAT للصق التنسيق، باستثناء التحقّق من صحة البيانات. تبقى القيم الأصلية في النطاق A1:D10 بدون تغيير.

يظهر أدناه بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

قص الخلايا ولصقها

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام CutPasteRequest. يقص النطاق A1:D10 ويستخدم الـ PasteType تعداد مع PASTE_NORMAL للصق قيمه وصيغه وتنسيقه وعمليات الدمج في الـ النطاق F1:I10 في الورقة نفسها. تتم إزالة محتويات خلايا النطاق المصدر الأصلي.

يظهر أدناه بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

تكرار صيغة على نطاق

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام RepeatCellRequest لنسخ الصيغة =FLOOR(A1*PI()) إلى النطاق B1:D10. يزداد نطاق الصيغة تلقائيًا لكل صف وعمود في النطاق، بدءًا من الخلية العلوية اليمنى. على سبيل المثال، تحتوي الخلية B1 على الصيغة =FLOOR(A1*PI())، بينما تحتوي الخلية D6 على الصيغة =FLOOR(C6*PI()).

يظهر أدناه بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

ترتيب نطاق باستخدام مواصفات ترتيب متعددة

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام SortRangeRequest لترتيب النطاق A1:D10، أولاً حسب العمود B بترتيب تصاعدي، ثم حسب العمود C بترتيب تنازلي، ثم حسب العمود D بترتيب تنازلي.

يظهر أدناه بروتوكول الطلب.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}