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

تتيح لك 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,
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	متوفّر	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	1/3/2016
3	باب	$15	2	3/15/2016
4	المحرك	$100	1	3/20/2016
5	مجاميع	135.5 دولار أمريكي	7	3/20/2016

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

عند كتابة قيم في نطاق، من الممكن تجنُّب تغيير بعض الخلايا الحالية من خلال ضبط عناصر الصفيف المقابلة على 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,
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	متوفّر	تاريخ الشحن
2	العجلة	$1,00	4	2016/4/1
3	باب	2 دولار أميركي (أو ما يعادلهما بالعملة المحلية)	2	‎4/15/2016
4	المحرك		1
5	مجاميع	$3,00	7	‎4/15/2016

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

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

بدءًا من ورقة فارغة، يوضّح نموذج الرمز البرمجي التالي 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,
    }
  ],
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	متوفّر	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	1/3/2016
3	باب
4	المحرك
5

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

بدءًا من ورقة فارغة، يوضِّح نموذج الرمز البرمجي التالي 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,
}

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

	A	ب	C	D	E
1	البيانات	123.45	صواب	=MAX(D2:D4)	10
2

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

إلحاق القيم

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	متوفّر	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	1/3/2016
3

يوضّح نموذج الرمز البرمجي التالي 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,
  }
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	متوفّر	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	1/3/2016
3	باب	$15	2	3/15/2016
4	المحرك	$100	1	3/20/2016
5