خدمة المواقع
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك خدمة الخصائص تخزين بيانات بسيطة في أزواج المفتاح/القيمة ضمن نطاق نص برمجي واحد أو مستخدم واحد لنص برمجي أو مستند واحد يتم فيه استخدام إضافة. ويتم استخدامها عادةً لتخزين إعدادات المطوّر أو إعدادات المستخدم المفضّلة. لا تتم مشاركة الخصائص بين النصوص البرمجية مطلقًا.
للاطّلاع على الحصص اليومية وحدود مساحة التخزين لخدمة "المواقع"، يُرجى الاطّلاع على حصص خدمات Google.
مقارنة بين متاجر المواقع
يوفّر العنصر العام
PropertiesService
ثلاث طرق، يعرض كل منها عنصرًا مشابهًا
Properties
ولكن مع حقوق وصول مختلفة، كما هو موضّح في الجدول التالي:
|
خصائص النص البرمجي |
خصائص المستخدمين |
خصائص المستند |
طريقة الوصول |
getScriptProperties() |
getUserProperties() |
getDocumentProperties() |
البيانات المشترَكة بين |
جميع مستخدمي نص برمجي أو إضافة أو تطبيق ويب |
المستخدم الحالي لنص برمجي أو إضافة أو تطبيق ويب |
جميع مستخدمي إضافة في المستند المفتوح |
يُستخدم عادةً في |
بيانات الإعداد على مستوى التطبيق، مثل اسم المستخدم وكلمة المرور لقاعدة البيانات الخارجية الخاصة بالمطوّر |
الإعدادات الخاصة بالمستخدم، مثل الوحدات المترية أو الإنجليزية |
البيانات الخاصة بالمستند، مثل عنوان URL المصدر لرسم بياني مضمَّن |
تخزّن خدمة "الخصائص" جميع البيانات كسلاسل في أزواج المفتاح/القيمة. يتم تلقائيًا تحويل أنواع البيانات التي ليست سلاسل حاليًا إلى سلاسل، بما في ذلك الطرق المضمّنة في الكائنات المحفوظة.
حفظ البيانات
لحفظ قيمة واحدة، استدعِ الدالة Properties.setProperty(key,
value)
من المتجر المناسب، كما هو موضّح في المثال التالي:
لحفظ البيانات بشكل مجمّع، مرِّر خريطة لأزواج المفتاح/القيمة إلى Properties.setProperties(properties)
.
يتم تخزين كل زوج مفتاح/قيمة من العنصر في المَعلمة كسمة منفصلة:
بيانات القراءة
لاسترداد قيمة واحدة سبق أن حفظتها، استدعِ الدالة
Properties.getProperty(key)
:
لاسترداد جميع القيم في مخزن السمات الحالي، استخدِم
Properties.getProperties()
:
تعديل البيانات
تعرض الطريقتان getProperty()
وgetProperties()
نسخة من البيانات المخزّنة، وليس عرضًا مباشرًا، لذا لن يؤدي تغيير الكائن المعروض إلى تعديل القيمة في مخزن المواقع. لتعديل البيانات في المتجر، ما عليك سوى حفظها مرة أخرى:
حذف البيانات
لحذف قيمة واحدة، استخدِم الرمز
Properties.deleteProperty(key)
:
لحذف جميع السمات في المتجر الحالي، استخدِم الأمر
Properties.deleteAllProperties()
:
إدارة مواقع النص البرمجي يدويًا
يمكنك إضافة ما يصل إلى خمسين موقعًا مخصّصًا يدويًا، كسلاسل في أزواج مفتاح-قيمة، من صفحة إعدادات المشروع. لإضافة أكثر من خمسين موقعًا، عليك إضافتها آليًا باستخدام الطرق الموضّحة أعلاه في قسم حفظ البيانات.
عند ضبط خصائص النص البرمجي من صفحة إعدادات المشروع، لا يمكنك الرجوع إلى متغيرات النص البرمجي.
إضافة خصائص النص البرمجي
- افتح مشروعك في "برمجة تطبيقات Google".
- على يمين الصفحة، انقر على إعدادات المشروع
.
- لإضافة الموقع الأول، انقر على إضافة خاصية للنص البرمجي ضمن خصائص النص البرمجي.
- لإضافة السمات الثانية واللاحقة، انقر على تعديل سمات النص البرمجي > إضافة سمة للنص البرمجي ضمن سمات النص البرمجي.
- بالنسبة إلى السمة، أدخِل اسم المفتاح.
- في حقل القيمة، أدخِل قيمة المفتاح.
- (اختياري) لإضافة المزيد من الخصائص، انقر على إضافة خاصية للنص البرمجي.
- انقر على حفظ مواقع النص البرمجي.
تعديل مواقع النص البرمجي
- افتح مشروعك في "برمجة تطبيقات Google".
- على يمين الصفحة، انقر على إعدادات المشروع
.
- ضمن خصائص النص البرمجي، انقر على تعديل خصائص النص البرمجي.
- أجرِ تغييرات على اسم المفتاح وقيمته لكل موقع تريد تغييره.
- انقر على حفظ مواقع النص البرمجي.
حذف مواقع النص البرمجي
- افتح مشروعك في "برمجة تطبيقات Google".
- على يمين الصفحة، انقر على إعدادات المشروع
.
- ضمن خصائص النص البرمجي، انقر على تعديل خصائص النص البرمجي.
- بجانب الموقع الذي تريد حذفه، انقر على "إزالة" close.
- انقر على حفظ مواقع النص البرمجي.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Properties service allows you to store simple data as key-value pairs, with separate stores for script, user, and document properties.\u003c/p\u003e\n"],["\u003cp\u003eData is stored as strings and automatically converted if it's a different data type, with access varying depending on the chosen property store.\u003c/p\u003e\n"],["\u003cp\u003eYou can save, read, modify, and delete data within these property stores using specific methods provided by the Properties service.\u003c/p\u003e\n"],["\u003cp\u003eScript properties can also be managed manually through the project settings page for a limited number of custom properties.\u003c/p\u003e\n"]]],[],null,["# Properties Service\n\nThe [Properties service](/apps-script/reference/properties) lets you store\nsimple data in key-value pairs scoped to one script, one user of a script, or\none document in which an [add-on](/workspace/add-ons/overview) is used. It is\ntypically used to store developer configuration or user preferences. Properties\nare never shared between scripts.\n\nTo view the daily quotas and storage limits for the Properties service, see\n[Quotas for Google Services](/apps-script/guides/services/quotas).\n\nComparison of property stores\n-----------------------------\n\nThe\n[`PropertiesService`](/apps-script/reference/properties/properties-service)\nglobal object offers three methods, each of which returns a similar\n[`Properties`](/apps-script/reference/properties/properties)\nobject but with different access rights, as shown in the following table:\n\n| | Script Properties | User Properties | Document Properties |\n|--------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|\n| Method to access | [getScriptProperties()](/apps-script/reference/properties/properties-service#getScriptProperties()) | [getUserProperties()](/apps-script/reference/properties/properties-service#getUserProperties()) | [getDocumentProperties()](/apps-script/reference/properties/properties-service#getDocumentProperties()) |\n| Data shared among | All users of a script, add-on, or web app | The current user of a script, add-on, or web app | All users of an add-on in the open document |\n| Typically used for | App-wide configuration data, like the username and password for the developer's external database | User-specific settings, like metric or imperial units | Document-specific data, like the source URL for an embedded chart |\n\nData format\n-----------\n\nThe Properties service stores all data as strings in key-value pairs. Data types\nthat are not already strings are automatically converted to strings, including\nmethods contained within saved objects.\n\nSaving data\n-----------\n\nTo save a single value, call the method [`Properties.setProperty(key,\nvalue)`](/apps-script/reference/properties/properties#setProperty(String,String))\nof the appropriate store, as shown in the following example: \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Set a property in each of the three property stores.\n const scriptProperties = PropertiesService.getScriptProperties();\n const userProperties = PropertiesService.getUserProperties();\n const documentProperties = PropertiesService.getDocumentProperties();\n\n scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');\n userProperties.setProperty('DISPLAY_UNITS', 'metric');\n documentProperties.setProperty('SOURCE_DATA_ID',\n '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nTo save data in bulk, pass a map of key-value pairs to\n[`Properties.setProperties(properties)`](/apps-script/reference/properties/properties#setProperties(Object)).\nEach key-value pair of the object in the parameter is stored as a separate\nproperty: \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Set multiple script properties in one call.\n const scriptProperties = PropertiesService.getScriptProperties();\n scriptProperties.setProperties({\n 'cow': 'moo',\n 'sheep': 'baa',\n 'chicken': 'cluck'\n });\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nReading data\n------------\n\nTo retrieve a single value that you have previously saved, call\n[`Properties.getProperty(key)`](/apps-script/reference/properties/properties#getProperty(String)): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Get the value for the user property 'DISPLAY_UNITS'.\n const userProperties = PropertiesService.getUserProperties();\n const units = userProperties.getProperty('DISPLAY_UNITS');\n console.log('values of units %s', units);\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nTo retrieve all values in the current property store, call\n[`Properties.getProperties()`](/apps-script/reference/properties/properties#getProperties()): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Get multiple script properties in one call, then log them all.\n const scriptProperties = PropertiesService.getScriptProperties();\n const data = scriptProperties.getProperties();\n for (const key in data) {\n console.log('Key: %s, Value: %s', key, data[key]);\n }\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nModifying data\n--------------\n\nThe methods `getProperty()` and `getProperties()` return a copy of the stored\ndata, not a live view, so changing the returned object will not update the value\nin the property store. To update the data in the store, simply save it again: \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Change the unit type in the user property 'DISPLAY_UNITS'.\n const userProperties = PropertiesService.getUserProperties();\n let units = userProperties.getProperty('DISPLAY_UNITS');\n units = 'imperial'; // Only changes local value, not stored value.\n userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nDeleting data\n-------------\n\nTo delete a single value, call\n[`Properties.deleteProperty(key)`](/apps-script/reference/properties/properties#deleteProperty(String)): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Delete the user property 'DISPLAY_UNITS'.\n const userProperties = PropertiesService.getUserProperties();\n userProperties.deleteProperty('DISPLAY_UNITS');\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nTo delete all properties in the current store, call\n[`Properties.deleteAllProperties()`](/apps-script/reference/properties/properties#deleteAllProperties()): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Get user properties in the current script.\n const userProperties = PropertiesService.getUserProperties();\n // Delete all user properties in the current script.\n userProperties.deleteAllProperties();\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nManage script properties manually\n---------------------------------\n\nYou can manually add up to fifty custom properties, as strings in key-value\npairs, from the project settings page. To add more than fifty properties, you\nneed to add them programmatically using the methods described above in\n[Saving data](#saving-data).\nWhen you set script properties from the project settings page, you can't\nreference script variables.\n\n### Add script properties\n\n1. Open your Apps Script project.\n2. At the left, click **Project Settings** .\n3. To add the first property, under **Script Properties** click **Add script property**.\n4. To add second and subsequent properties, under **Script Properties** click **Edit script properties** \\\u003e **Add script property**.\n5. For **Property**, enter the key name.\n6. For **Value**, enter the value for the key.\n7. (Optional) To add more properties, click **Add script property**.\n8. Click **Save script properties**.\n\n### Edit script properties\n\n1. Open your Apps Script project.\n2. At the left, click **Project Settings** .\n3. Under **Script Properties** , click **Edit script properties**.\n4. Make changes to the key name and key value for each property you want to change.\n5. Click **Save script properties**.\n\n### Delete script properties\n\n1. Open your Apps Script project.\n2. At the left, click **Project Settings** .\n3. Under **Script Properties** , click **Edit script properties**.\n4. Next to the property that you want to delete, click Remove close.\n5. Click **Save script properties**."]]