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

تتيح لك 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 لتطبيق قاعدة التحقق من صحة البيانات، حيث "value > 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"
          }
        ]
      }
    }
  ]
}