الكتابة الأساسية

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

تجدر الإشارة إلى أنّه يمكن أيضًا كتابة قيم الخلايا باستخدام الأسلوب spreadsheet.batchUpdate ، والذي يمكن أن يكون مفيدًا إذا كنت تريد تعديل تنسيق الخلايا أو خصائص أخرى في الوقت نفسه لا يؤثّر فيها مصدر spreadsheets.values. على سبيل المثال، إذا كنت تريد نسخ نطاق خلايا من ورقة بيانات إلى أخرى مع استبدال كل من صيغة الخلية وتنسيق الخلية، يمكنك استخدام الأسلوب UpdateCellsRequest مع spreadsheet.batchUpdate.

ومع ذلك، بالنسبة إلى عمليات كتابة القيم البسيطة، من الأسهل استخدام الطريقة spreadsheets.values.update أو الطريقة spreadsheets.values.batchUpdate.

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

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

كتابة نطاق واحد

بدءًا من جدول بيانات جديد فارغ، يوضّح نموذج الرمز التالي spreadsheets.values.update كيفية كتابة القيم في نطاق. إنّ مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (مثل ما إذا كان سيتم تحويل سلسلة إلى تاريخ أم لا).

نص الطلب هو كائن ValueRange يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم بالقيم منظَّمة حسب الصفوف. يتم استبدال القيم الحالية في النطاق المستهدَف.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

تتكوّن الاستجابة من كائن UpdateValuesResponse ، مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

تظهر ورقة البيانات الناتجة على النحو التالي:

الكتابة بشكل انتقائي في نطاق

عند كتابة قيم في نطاق، من الممكن تجنُّب تغيير بعض الخلايا الحالية من خلال ضبط عناصر الصفيف المقابلة على null. من الممكن أيضًا محو خلية عن طريق كتابة سلسلة فارغة ("") فيها.

بدءًا من ورقة بيانات تحتوي على البيانات نفسها التي تم إنشاؤها من خلال المثال السابق، يوضّح نموذج الرمز البرمجي التالي spreadsheets.values.update كيفية كتابة القيم في النطاق B1:D4، مع إبقاء بعض الخلايا بدون تغيير وحذف الخلايا الأخرى بشكل انتقائي. إنّ مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (مثل ما إذا كان سيتم تحويل سلسلة إلى تاريخ أم لا).

نص الطلب هو كائن ValueRange يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ الصفائف هي قوائم بالقيم منظَّمة حسب العمود.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

يسرد الحقل values هنا التغييرات التي تم إجراؤها على كل عمود في النطاق. يشير الجدول الدوار الأول إلى أنّه يجب ترك B1 بدون تغيير (بسبب عنصر الجدول الدوارnull)، بينما يجب محو B4 (سلسلة فارغة). تم تعديل قيم الخليتين B2 وB3. تُجري الصفيف الثالث العمليات نفسها على العمود D، في حين يشير الصفيف الثاني الفارغ إلى أنّه يجب ترك العمود C بدون تغيير.

تتألف الاستجابة من كائن UpdateValuesResponse مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

تظهر ورقة البيانات الناتجة على النحو التالي:

يُرجى العلم أنّ صف "المجاميع"، على الرغم من عدم تغييره مباشرةً من خلال هذا الطلب، فإنه يتغيّر لأنّ خلاياه تحتوي على صِيَغ تعتمد على الخلايا التي تم تغييرها.

الكتابة في نطاقات متعددة

بدءًا من ورقة فارغة، يوضّح نموذج الرمز البرمجي التالي spreadsheets.values.batchUpdate كيفية كتابة القيم في النطاقَين "الورقة1!A1:A4" و "الورقة1!B1:D2". يتم استبدال القيم الحالية في النطاق المستهدَف. يتألّف جسم الطلب من عنصر ValueInputOption يشرح كيفية تفسير بيانات الإدخال، بالإضافة إلى مصفوفة من عناصر ValueRange المرتبطة بكل نطاق مكتوب. يحدِّد الحقل majorDimension ما إذا كان سيتم تفسير المصفوفات المضمّنة على أنّها مصفوفات من الأعمدة أو الصفوف.

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

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

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

تتألّف الاستجابة من عنصر يسرد إحصاءات الخلايا المعدَّلة ومصفوفة من عناصر UpdateValuesResponse ، واحدة لكل نطاق معدَّل. على سبيل المثال:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

تظهر ورقة البيانات الناتجة على النحو التالي:

كتابة القيم بدون تحليل

بدءًا من ورقة فارغة، يوضِّح نموذج الرمز البرمجي التالي spreadsheets.values.update كيفية كتابة القيم في النطاق "الورقة1!‎A1:E1"، ولكنّه يستخدِم مَعلمة الطلب RAW ValueInputOption لمنع تحليل السلاسل المكتوبة كسِيَغ أو قيم منطقية أو أرقام. تظهر هذه القيم كنصوص ويتم ضبط محاذاة النص على "متوسط" في ورقة البيانات.

نص الطلب هو كائن ValueRange يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم بالقيم منظَّمة حسب الصفوف. يتم استبدال القيم الحالية في النطاق المستهدَف.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

تتألف الاستجابة من كائن UpdateValuesResponse مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

تظهر ورقة البيانات الناتجة على النحو التالي:

يُرجى العِلم أنّ القيمة "صحيح" تكون في المنتصف وهي قيمة منطقية، في حين تكون القيمة "123.45" مُعدَّة للعرض على يمين الصفحة لأنّها رقم، وتكون القيمة "10" مُعدَّة للعرض على يمين الصفحة لأنّها سلسلة. لا يتم تحليل الصيغة، وتظهر أيضًا كسلسلة.

إلحاق القيم

ابدأ بجدول مثل الجدول أدناه:

يوضّح نموذج الرمز البرمجي التالي spreadsheets.values.append كيفية إضافة صفَّين جديدَين من القيم بدءًا من الصف 3. إنّ مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (مثل ما إذا كان سيتم تحويل سلسلة إلى تاريخ أم لا).

نص الطلب هو كائن ValueRange يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم بالقيم منظَّمة حسب الصفوف.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

تتألف الاستجابة من كائن AppendValuesResponse مثل هذا الكائن:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

تظهر ورقة البيانات الناتجة على النحو التالي: