لمنح صنّاع النماذج مزيدًا من التحكّم في تحديد المستخدمين الذين يمكنهم الردّ، نقدّم عناصر تحكّم دقيقة للمجيبين. ستظهر النماذج التي تم إنشاؤها باستخدام واجهة برمجة التطبيقات بعد 31 كانون الثاني (يناير) 2026 في حالة "غير منشور" تلقائيًا. لمزيد من المعلومات، يُرجى الاطّلاع على تغييرات واجهة برمجة التطبيقات في "نماذج Google".
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
لإضافة محتوى إلى نموذج أو تعديل الإعدادات أو البيانات الوصفية أو المحتوى، استخدِم طريقة batchUpdate() التي تجمع التغييرات معًا في حزمة، وبالتالي إذا تعذّر تنفيذ أحد الطلبات، لن يتم تنفيذ أي من التغييرات الأخرى (التي قد تكون مرتبطة).
تعرض الطريقة batchUpdate() نص استجابة يتضمّن استجابة لكل طلب. يحتل كل ردّ الفهرس نفسه الذي يحتله الطلب المقابل، وفي حال عدم توفّر ردّ مناسب للطلب، سيكون الردّ في هذا الفهرس فارغًا.
قبل البدء
نفِّذ المهام التالية قبل المتابعة إلى المهام الواردة في هذه الصفحة:
أكمِل عملية التفويض/المصادقة وإعداد بيانات الاعتماد باتّباع تعليمات "برنامج الاستخدام المبكر"
تعديل البيانات الوصفية أو الإعدادات أو العناصر
يوضّح المثال التالي كيفية تعديل البيانات الوصفية الخاصة بنموذج، ولكن البنية هي نفسها بالنسبة إلى المحتوى والإعدادات، إذ تستخدم طلبات updateItem أو updateSettings بدلاً من updateFormInfo. في كل طلب، عليك تقديم اسم الحقل الذي تريد تغييره والقيمة المعدَّلة، بالإضافة إلى قيمة updateMask للحدّ من التغييرات على الحقول التي حدّدتها.
REST
لتعديل وصف النموذج، استخدِم طريقة
batchUpdate()
مع رقم تعريف النموذج وقيمة الوصف المعدَّلة.
نموذج نص الطلب
"requests":[{"updateFormInfo":{"info":{"description":"Please complete this quiz based on this week's readings for class."},"updateMask":"description"}}]
fromapiclientimportdiscoveryfromhttplib2importHttpfromoauth2clientimportclient,file,toolsSCOPES="https://www.googleapis.com/auth/forms.body"DISCOVERY_DOC="https://forms.googleapis.com/$discovery/rest?version=v1"store=file.Storage("token.json")creds=Noneifnotcredsorcreds.invalid:flow=client.flow_from_clientsecrets("client_secrets.json",SCOPES)creds=tools.run_flow(flow,store)form_service=discovery.build("forms","v1",http=creds.authorize(Http()),discoveryServiceUrl=DISCOVERY_DOC,static_discovery=False,)form={"info":{"title":"Update metadata example for Forms API!",}}# Creates the initial FormcreateResult=form_service.forms().create(body=form).execute()# Request body to add description to a Formupdate={"requests":[{"updateFormInfo":{"info":{"description":("Please complete this quiz based on this week's"" readings for class.")},"updateMask":"description",}}]}# Update the form with a descriptionquestion_setting=(form_service.forms().batchUpdate(formId=createResult["formId"],body=update).execute())# Print the result to see it now has a descriptiongetresult=form_service.forms().get(formId=createResult["formId"]).execute()print(getresult)
importpathfrom'path';import{forms}from'@googleapis/forms';import{authenticate}from'@google-cloud/local-auth';asyncfunctionupdateForm(){constauthClient=awaitauthenticate({keyfilePath:path.join(__dirname,'credentials.json'),scopes:'https://www.googleapis.com/auth/drive',});constformsClient=forms({version:'v1',auth:authClient,});constnewForm={info:{title:'Creating a new form for batchUpdate in Node',},};constcreateResponse=awaitformsClient.forms.create({requestBody:newForm,});console.log('New formId was: '+createResponse.data.formId);// Request body to add description to a Formconstupdate={requests:[{updateFormInfo:{info:{description:'Please complete this quiz based on this week\'s readings for class.',},updateMask:'description',},},],};constres=awaitformsClient.forms.batchUpdate({formId:createResponse.data.formId,requestBody:update,});console.log(res.data);returnres.data;}
إضافة عنصر
يوضّح المثال التالي كيفية إضافة محتوى جديد إلى نموذج. عند إضافة محتوى جديد، يجب توفير موقع جغرافي مع فهرس يتم فيه إدراج المحتوى الجديد. على سبيل المثال، سيؤدي الموقع الذي يتضمّن الفهرس 0 إلى إدراج المحتوى في بداية النموذج.
REST
لإضافة عنصر إلى النموذج، استدعِ طريقة
batchUpdate()
باستخدام معرّف النموذج ومعلومات العنصر والموقع الجغرافي المطلوب.
نموذج نص الطلب
"requests":[{"createItem":{"item":{"title":"Homework video","description":"Quizzes in Google Forms","videoItem":{"video":{"youtubeUri":"https://www.youtube.com/watch?v=Lt5HqPvM-eI"}}},"location":{"index":0}}]
fromapiclientimportdiscoveryfromhttplib2importHttpfromoauth2clientimportclient,file,toolsSCOPES="https://www.googleapis.com/auth/forms.body"DISCOVERY_DOC="https://forms.googleapis.com/$discovery/rest?version=v1"store=file.Storage("token.json")creds=Noneifnotcredsorcreds.invalid:flow=client.flow_from_clientsecrets("client_secrets.json",SCOPES)creds=tools.run_flow(flow,store)form_service=discovery.build("forms","v1",http=creds.authorize(Http()),discoveryServiceUrl=DISCOVERY_DOC,static_discovery=False,)form={"info":{"title":"Update item example for Forms API",}}# Creates the initial FormcreateResult=form_service.forms().create(body=form).execute()# Request body to add a video item to a Formupdate={"requests":[{"createItem":{"item":{"title":"Homework video","description":"Quizzes in Google Forms","videoItem":{"video":{"youtubeUri":("https://www.youtube.com/watch?v=Lt5HqPvM-eI")}},},"location":{"index":0},}}]}# Add the video to the formquestion_setting=(form_service.forms().batchUpdate(formId=createResult["formId"],body=update).execute())# Print the result to see it now has a videoresult=form_service.forms().get(formId=createResult["formId"]).execute()print(result)
importpathfrom'path';import{forms}from'@googleapis/forms';import{authenticate}from'@google-cloud/local-auth';asyncfunctionaddItem(){constauthClient=awaitauthenticate({keyfilePath:path.join(__dirname,'credentials.json'),scopes:'https://www.googleapis.com/auth/drive',});constformsClient=forms({version:'v1',auth:authClient,});constnewForm={info:{title:'Creating a new form for batchUpdate in Node',},};constcreateResponse=awaitformsClient.forms.create({requestBody:newForm,});console.log('New formId was: '+createResponse.data.formId);// Request body to add video item to a Formconstupdate={requests:[{createItem:{item:{title:'Homework video',description:'Quizzes in Google Forms',videoItem:{video:{youtubeUri:'https://www.youtube.com/watch?v=Lt5HqPvM-eI',},},},location:{index:0,},},},],};constupdateResponse=awaitformsClient.forms.batchUpdate({formId:createResponse.data.formId,requestBody:update,});console.log(updateResponse.data);returnupdateResponse.data;}
ترتيب الطلبات
يقبل الأسلوب batchUpdate()
مجموعة من الطلبات الفرعية، مثل createItem وupdateItem.
يتم التحقّق من صحة الطلبات الفرعية واحدًا تلو الآخر بالترتيب الذي تم تقديمه.
مثال: يحتوي طلب batchUpdate على مصفوفة requests تتضمّن طلبَين فرعيَين createItem. يحتوي الطلب الفرعي (أ) على location.index 0 ويحتوي الطلب الفرعي (ب) على location.index 1. إذا كانت المصفوفة requests هي [أ، ب]، ستنجح batchUpdate. إذا كان الصفيف [B, A]، سيتعذّر تنفيذ batchUpdate، لأنّ location.index
1 غير صالح ما لم يحتوي النموذج على عنصر في الفهرس 0.
تاريخ التعديل الأخير: 2025-09-10 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-10 (حسب التوقيت العالمي المتفَّق عليه)"],[],["The `batchUpdate()` method is used to modify forms, allowing for updates to metadata, settings, or content and the addition of new items. It groups changes, ensuring that if one fails, none are applied. When updating, the method requires the field name, updated value, and `updateMask`. Adding content requires specifying the item details and insertion `location` by index. The method executes sub-requests sequentially, validating each in order. The order in which you place requests in an array matters when creating items.\n"],null,["# Update a form or quiz\n\nTo add content to a form or update the settings, metadata, or content, use the\n`batchUpdate()` method, which groups changes together in a batch so that if one\nrequest fails, none of the other (potentially dependent) changes are written.\n\nThe `batchUpdate()` method returns a response body, within which is a response\nfor each request. Each response occupies the same index as the corresponding\nrequest; for requests with no applicable response, the response at that index\nwill be empty.\n\nBefore you begin\n----------------\n\nPerform the following tasks before proceeding with the tasks on this page:\n\n- Complete authorization/authentication and credentials setup in the Early Adopter Program instructions\n\nUpdate metadata, settings, or items\n-----------------------------------\n\nThe following example shows how to update a form's metadata, but the structure\nis the same for content and settings---they use the `updateItem` or\n`updateSettings` requests instead of `updateFormInfo`. For each request, you\nsupply the name of the field to be changed and the updated value, along with\nan `updateMask` value to limit changes to the fields you've specified. \n\n### REST\n\nTo update the form's description, call the\n[`batchUpdate()`](/workspace/forms/api/reference/rest/v1/forms/batchUpdate)\nmethod with the form ID and the updated description value.\n\n**Sample request body** \n\n \"requests\": [{\n \"updateFormInfo\": {\n \"info\": {\n \"description\": \"Please complete this quiz based on this week's readings for class.\"\n },\n \"updateMask\": \"description\"\n }\n }]\n\n### Python\n\nforms/snippets/update_form.py \n[View on GitHub](https://github.com/googleworkspace/python-samples/blob/main/forms/snippets/update_form.py) \n\n```python\nfrom apiclient import discovery\nfrom httplib2 import Http\nfrom oauth2client import client, file, tools\n\nSCOPES = \"https://www.googleapis.com/auth/forms.body\"\nDISCOVERY_DOC = \"https://forms.googleapis.com/$discovery/rest?version=v1\"\n\nstore = file.Storage(\"token.json\")\ncreds = None\nif not creds or creds.invalid:\n flow = client.flow_from_clientsecrets(\"client_secrets.json\", SCOPES)\n creds = tools.run_flow(flow, store)\n\nform_service = discovery.build(\n \"forms\",\n \"v1\",\n http=creds.authorize(Http()),\n discoveryServiceUrl=DISCOVERY_DOC,\n static_discovery=False,\n)\n\nform = {\n \"info\": {\n \"title\": \"Update metadata example for Forms API!\",\n }\n}\n\n# Creates the initial Form\ncreateResult = form_service.forms().create(body=form).execute()\n\n# Request body to add description to a Form\nupdate = {\n \"requests\": [\n {\n \"updateFormInfo\": {\n \"info\": {\n \"description\": (\n \"Please complete this quiz based on this week's\"\n \" readings for class.\"\n )\n },\n \"updateMask\": \"description\",\n }\n }\n ]\n}\n\n# Update the form with a description\nquestion_setting = (\n form_service.forms()\n .batchUpdate(formId=createResult[\"formId\"], body=update)\n .execute()\n)\n\n# Print the result to see it now has a description\ngetresult = form_service.forms().get(formId=createResult[\"formId\"]).execute()\nprint(getresult)\n```\n\n### Node.js\n\nforms/snippets/update_form.js \n[View on GitHub](https://github.com/googleworkspace/node-samples/blob/main/forms/snippets/update_form.js) \n\n```javascript\n'use strict';\n\nconst path = require('path');\nconst google = require('@googleapis/forms');\nconst {authenticate} = require('@google-cloud/local-auth');\n\nasync function runSample(query) {\n const authClient = await authenticate({\n keyfilePath: path.join(__dirname, 'credentials.json'),\n scopes: 'https://www.googleapis.com/auth/drive',\n });\n const forms = google.forms({\n version: 'v1',\n auth: authClient,\n });\n const newForm = {\n info: {\n title: 'Creating a new form for batchUpdate in Node',\n },\n };\n const createResponse = await forms.forms.create({\n requestBody: newForm,\n });\n console.log('New formId was: ' + createResponse.data.formId);\n\n // Request body to add description to a Form\n const update = {\n requests: [\n {\n updateFormInfo: {\n info: {\n description:\n 'Please complete this quiz based on this week\\'s readings for class.',\n },\n updateMask: 'description',\n },\n },\n ],\n };\n const res = await forms.forms.batchUpdate({\n formId: createResponse.data.formId,\n requestBody: update,\n });\n console.log(res.data);\n return res.data;\n}\n\nif (module === require.main) {\n runSample().catch(console.error);\n}\nmodule.exports = runSample;\n```\n\nAdd an item\n-----------\n\nThe following example shows how to add new content to a form. When adding new\ncontent, you must provide a location with an index where new content should be\ninserted. For instance, a location with index `0` will insert the content at\nthe beginning of the form. \n\n### REST\n\nTo add an item to the form, call the\n[`batchUpdate()`](/workspace/forms/api/reference/rest/v1/forms/batchUpdate)\nmethod with the form ID and the item's information and desired location.\n\n**Sample request body** \n\n \"requests\": [{\n \"createItem\": {\n \"item\": {\n \"title\": \"Homework video\",\n \"description\": \"Quizzes in Google Forms\",\n \"videoItem\": {\n \"video\": {\n \"youtubeUri\": \"https://www.youtube.com/watch?v=Lt5HqPvM-eI\"\n }\n }},\n \"location\": {\n \"index\": 0\n }\n }]\n\n### Python\n\nforms/snippets/add_item.py \n[View on GitHub](https://github.com/googleworkspace/python-samples/blob/main/forms/snippets/add_item.py) \n\n```python\nfrom apiclient import discovery\nfrom httplib2 import Http\nfrom oauth2client import client, file, tools\n\nSCOPES = \"https://www.googleapis.com/auth/forms.body\"\nDISCOVERY_DOC = \"https://forms.googleapis.com/$discovery/rest?version=v1\"\n\nstore = file.Storage(\"token.json\")\ncreds = None\nif not creds or creds.invalid:\n flow = client.flow_from_clientsecrets(\"client_secrets.json\", SCOPES)\n creds = tools.run_flow(flow, store)\n\nform_service = discovery.build(\n \"forms\",\n \"v1\",\n http=creds.authorize(Http()),\n discoveryServiceUrl=DISCOVERY_DOC,\n static_discovery=False,\n)\n\nform = {\n \"info\": {\n \"title\": \"Update item example for Forms API\",\n }\n}\n\n# Creates the initial Form\ncreateResult = form_service.forms().create(body=form).execute()\n\n# Request body to add a video item to a Form\nupdate = {\n \"requests\": [\n {\n \"createItem\": {\n \"item\": {\n \"title\": \"Homework video\",\n \"description\": \"Quizzes in Google Forms\",\n \"videoItem\": {\n \"video\": {\n \"youtubeUri\": (\n \"https://www.youtube.com/watch?v=Lt5HqPvM-eI\"\n )\n }\n },\n },\n \"location\": {\"index\": 0},\n }\n }\n ]\n}\n\n# Add the video to the form\nquestion_setting = (\n form_service.forms()\n .batchUpdate(formId=createResult[\"formId\"], body=update)\n .execute()\n)\n\n# Print the result to see it now has a video\nresult = form_service.forms().get(formId=createResult[\"formId\"]).execute()\nprint(result)\n```\n\n### Node.js\n\nforms/snippets/add_item.js \n[View on GitHub](https://github.com/googleworkspace/node-samples/blob/main/forms/snippets/add_item.js) \n\n```javascript\n'use strict';\n\nconst path = require('path');\nconst google = require('@googleapis/forms');\nconst {authenticate} = require('@google-cloud/local-auth');\n\nasync function runSample(query) {\n const authClient = await authenticate({\n keyfilePath: path.join(__dirname, 'credentials.json'),\n scopes: 'https://www.googleapis.com/auth/drive',\n });\n const forms = google.forms({\n version: 'v1',\n auth: authClient,\n });\n const newForm = {\n info: {\n title: 'Creating a new form for batchUpdate in Node',\n },\n };\n const createResponse = await forms.forms.create({\n requestBody: newForm,\n });\n console.log('New formId was: ' + createResponse.data.formId);\n\n // Request body to add video item to a Form\n const update = {\n requests: [\n {\n createItem: {\n item: {\n title: 'Homework video',\n description: 'Quizzes in Google Forms',\n videoItem: {\n video: {\n youtubeUri: 'https://www.youtube.com/watch?v=Lt5HqPvM-eI',\n },\n },\n },\n location: {\n index: 0,\n },\n },\n },\n ],\n };\n const updateResponse = await forms.forms.batchUpdate({\n formId: createResponse.data.formId,\n requestBody: update,\n });\n console.log(updateResponse.data);\n return updateResponse.data;\n}\n\nif (module === require.main) {\n runSample().catch(console.error);\n}\nmodule.exports = runSample;\n```\n\nRequest order\n-------------\n\nThe [`batchUpdate()`](/workspace/forms/api/reference/rest/v1/forms/batchUpdate)\nmethod accepts an array of sub-requests such as `createItem` and `updateItem`.\nSub-requests are validated one at a time in the order they are provided.\n\nExample: A `batchUpdate` request has a `requests` array with two `createItem`\nsub-requests. Sub-request A has `location.index` 0 and sub-request B has\n`location.index` 1. If the `requests` array is \\[A, B\\], `batchUpdate` will\nsucceed. If the array is \\[B, A\\], `batchUpdate` will fail, since `location.index`\n1 is not valid unless the form already contains an item at index 0."]]