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

تسمح لك 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. مثال على النطاق هو Sheet1!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,
}

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

	جيم	B	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	2016/3/1
3	باب	$15	2	2016/3/15
4	المحرك	$100	1	2016/3/20
5	مجاميع	135.5 دولار أمريكي	7	2016/3/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,
}

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

	جيم	B	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	1.00 دولار أمريكي (أو ما يعادله بالعملة المحلية)	4	1/4/2016
3	باب	2 دولار أميركي (أو ما يعادلهما بالعملة المحلية)	2	2016/4/15
4	المحرك		1
5	مجاميع	3.00 دولارات أمريكية (أو ما يعادلها بالعملة المحلية)	7	2016/4/15

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

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

بدءًا من ورقة فارغة، يعرض نموذج الرمز البرمجي spreadsheets.values.batchUpdate التالي كيفية كتابة القيم في النطاقَين Sheet1!A1:A4 وSheet1!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,
    }
  ],
}

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

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

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

بدءًا من ورقة فارغة، يعرض نموذج الرمز البرمجي spreadsheets.values.update التالي كيفية كتابة القيم في النطاق Sheet1!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,
}

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

	جيم	B	C	D	E
1	البيانات	123.45	TRUE	=MAX(D2:D4)	10
2

لاحظ أن "TRUE" يتم توسيطها وهي قيمة منطقية، في حين يتم ضبط "123.45" لليمين لأنه رقم، ويتم ترك "10" مُبررًا لأنه سلسلة. لا يتم تحليل الصيغة، وتظهر أيضًا كسلسلة.

إلحاق القيم

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

	جيم	B	C	D
1	المنتج/الخدمة	التكلفة	مخزن	تاريخ الشحن
2	العجلة	20.50 دولار أمريكي	4	2016/3/1
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,
  }
}

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

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