# ربط Google Sheets بالذكاء الاصطناعي: استدعِ نموذجًا من خلية > كيف تستدعي نموذج AI من Google Sheets عبر Apps Script، بصيغة في خلية أو من قائمة، وكم يكلف، وكيف تحمي مفتاح API. آخر تحديث: 2026-11-03 لتستدعي نموذج ذكاء اصطناعي من Google Sheets، أضف نصًا برمجيًا قصيرًا في Apps Script يرسل نص الخلية إلى واجهة API عبر UrlFetchApp ويكتب الإجابة. استخدمه صيغةً مثل `=ASK_AI(A2)`، أو من قائمة تملأ عمودًا كاملًا. واحفظ مفتاح API في Script Properties، ولا تضعه في خلية أبدًا. ## كيف يعمل؟ محرر Apps Script مدمج في Google Sheets، وتجده في القائمة Extensions > Apps Script. والدالة `UrlFetchApp.fetch` فيه ترسل طلبات على الويب، فيستطيع النص البرمجي أن يرسل التعليمة إلى واجهة API ويقرأ الرد. ويستدعي النص البرمجي أدناه واجهة Chat Completions بتنسيق OpenAI: العنوان الأساسي لدينا `https://api.5abeer.ai/v1` يليه `/chat/completions`، كما في [ما هو العنوان الأساسي؟](https://5abeer.ai/ar/guides/what-is-base-url). متوافق مع OpenAI: غيّر العنوان الأساسي واحتفظ بالكود نفسه. وكل إجابة طلب واحد مثل هذا: ```bash curl --request POST "https://api.5abeer.ai/v1/chat/completions" \ --header "Authorization: Bearer $KHABEER_API_KEY" \ --header "Content-Type: application/json" \ --data '{"model":"claude-sonnet-5.5","messages":[{"role":"user","content":"اكتب فكرة منتج في سطر واحد"}]}' ``` ```python import os import requests response = requests.post( "https://api.5abeer.ai/v1/chat/completions", headers={ "Authorization": f"Bearer {os.environ['KHABEER_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "claude-sonnet-5.5", "messages": [ { "role": "user", "content": "اكتب فكرة منتج في سطر واحد" } ] }, stream=False, timeout=60, ) response.raise_for_status() print(response.json()) ``` ويتيح لك النص البرمجي طريقتين لتشغيله: | | الصيغة | القائمة | | --- | --- | --- | | طريقة التشغيل | اكتب `=ASK_AI(A2)` في خلية | حدّد خلايا التعليمات، ثم 5abeer > Answer the selected cells | | حد الوقت | 30 ثانية لكل خلية | 6 دقائق لكل تشغيل | | متى ترسل طلبًا | كلما أُعيد حساب الخلية، مثل تعديل الصيغة أو تغيّر خلية تشير إليها | عند الضغط فقط | | ما يبقى في الجدول | صيغة تعمل باستمرار | قيم ثابتة في العمود التالي | | الأنسب لـ | خلايا قليلة | صفوف كثيرة، في تشغيل واحد أو أكثر | ## قبل أن تبدأ تحتاج إلى مفتاح API من خبير لمزوّد النموذج الذي يستدعيه النص البرمجي. ويعمل كل مفتاح مع نماذج مزوّد واحد، والنص البرمجي يستدعي [`claude-sonnet-5.5`](https://5abeer.ai/ar/models/claude-sonnet-5.5)، لذلك أنشئ مفتاحًا لنماذج Claude كما في [إنشاء مفتاح](https://5abeer.ai/ar/docs/start/keys.md#create). تحكّم في كل مفتاح: حد للإنفاق، وتاريخ انتهاء، وقائمة عناوين IP المسموح بها. وخصّص لهذا الجدول مفتاحًا خاصًا به، بحد إنفاق وتاريخ انتهاء، كما في [تحكّم في كل مفتاح](https://5abeer.ai/ar/docs/start/keys.md#controls)، حتى لا يكلفك أي خطأ في الجدول إلا القليل. ولا تقصر هذا المفتاح على عنوان IP الخاص بك، لأن Apps Script يرسل طلباته من خوادم Google لا من جهازك، فيرفض المفتاح عندها كل طلبات الجدول. ## أضف النص البرمجي ### 1. افتح Apps Script في جدولك، اختر Extensions > Apps Script. فيُفتح مشروع نص برمجي مرتبط بالجدول، فيه ملف اسمه `Code.gs`. ### 2. احفظ المفتاح في محرر Apps Script، افتح Project Settings، ثم أضف تحت Script Properties خاصية اسمها `KHABEER_API_KEY` وقيمتها مفتاحك من خبير، واحفظ. بهذا يبقى المفتاح خارج الكود وخارج الخلايا. ### 3. الصق الكود استبدل كل ما في `Code.gs` بهذا الكود، ثم احفظ: ```javascript // The key lives in Project Settings > Script Properties as KHABEER_API_KEY, never in this code or in a cell. const BASE_URL = "https://api.5abeer.ai/v1"; // 5abeer's OpenAI-format base URL const MODEL = "claude-sonnet-5.5"; /** * Sends a prompt to an AI model and returns its answer. * @param {string} prompt The question or instruction. * @return The model's answer. * @customfunction */ function ASK_AI(prompt) { if (prompt === "" || prompt == null) return ""; return askModel_(prompt); } function onOpen() { SpreadsheetApp.getUi() .createMenu("5abeer") .addItem("Test the key", "testKey") .addItem("Answer the selected cells", "answerSelection") .addToUi(); } function testKey() { SpreadsheetApp.getUi().alert(askModel_("Reply with the word OK.")); } function answerSelection() { const range = SpreadsheetApp.getActiveRange(); const prompts = range.getValues(); const out = range.offset(0, 1, prompts.length, 1); // the next column holds the answers const answers = out.getValues(); for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i][0]; if (prompt === "" || answers[i][0] !== "") continue; // skip empty and answered rows let answer = askModel_(prompt); if (/^[=+\-@]/.test(answer)) answer = "'" + answer; // keep the reply as text, never a formula out.getCell(i + 1, 1).setValue(answer); SpreadsheetApp.flush(); // keep each answer if the 6-minute limit stops the run } } function askModel_(prompt) { const key = PropertiesService.getScriptProperties().getProperty("KHABEER_API_KEY"); if (!key) throw new Error("Add KHABEER_API_KEY in Project Settings > Script Properties."); const response = UrlFetchApp.fetch(BASE_URL + "/chat/completions", { method: "post", contentType: "application/json", headers: { Authorization: "Bearer " + key }, payload: JSON.stringify({ model: MODEL, messages: [{ role: "user", content: String(prompt) }] }), muteHttpExceptions: true, }); const status = response.getResponseCode(); const text = response.getContentText(); if (status !== 200) throw new Error("5abeer API error " + status + ": " + text.slice(0, 200)); return JSON.parse(text).choices[0].message.content; } ``` ولاستخدام نموذج آخر، غيّر قيمة `MODEL` إلى معرّفه من [صفحة النماذج](https://5abeer.ai/ar/models)، واحفظ مفتاحًا لمزوّد ذلك النموذج. ويمكنك أن تكتب أسماء القائمة بالعربية مثلًا، بتغييرها في الدالة `onOpen`. ### 4. اختبر المفتاح أعد تحميل الجدول، فتظهر قائمة 5abeer في شريط القوائم. اختر 5abeer > Test the key، ووافق على الأذونات التي تطلبها Google في أول تشغيل. وظهور نافذة فيها رد النموذج يعني أن الإعداد يعمل. ويرسل هذا الاختبار طلبًا صغيرًا واحدًا مدفوعًا. ## استخدمه في خلية اكتب الصيغة في خلية، ومعها تعليمتك ومرجع الخلية: ```text =ASK_AI("Summarize in one sentence: " & A2) ``` ويمكنك أن تكتب التعليمة بالعربية أيضًا. ونفّذ خطوة اختبار المفتاح أولًا: فالصيغة لا تطلب الأذونات أبدًا، لذلك توافق عليها مرة واحدة من القائمة. ثم اسحب الصيغة إلى الأسفل لتعمل في كل صف. وكل خلية طلب مدفوع مستقل، وترسل طلبًا جديدًا كلما أُعيد حسابها. وللاحتفاظ بالإجابات وإيقاف الطلبات الجديدة، انسخ الخلايا والصقها في مكانها قيمًا فقط. ويجب أن تصل إجابة الخلية خلال 30 ثانية، وإلا ظهر فيها `#ERROR!`. كما يجري Sheets استدعاءً منفصلًا لكل خلية فيها الصيغة، فيصبح بطيئًا مع مئات الصفوف. وللإجابات الطويلة أو الصفوف الكثيرة، استخدم القائمة. ## املأ عمودًا من القائمة حدّد الخلايا التي فيها تعليماتك، في عمود واحد، ثم اختر 5abeer > Answer the selected cells. فتُكتب الإجابات في العمود التالي قيمًا ثابتة، فلا ترسل أي طلب بعد ذلك. ويتخطى النص البرمجي الخلايا الفارغة والصفوف التي فيها إجابة بالفعل، ويحفظ كل إجابة عند وصولها. وتوقف Google التشغيل بعد 6 دقائق، فإذا كان العمود طويلًا، شغّل القائمة مرة أخرى لتكمل من أول صف بلا إجابة. وأي رد يبدأ بالرمز `=` أو `+` أو `-` أو `@` يُحفظ نصًا، فلا يتحول إلى صيغة أبدًا. ## احمِ المفتاح النص البرمجي المرتبط بجدول يتبع قائمة الوصول نفسها التي للجدول، وخصائص Script Properties واحدة لكل من يشغّل النص البرمجي: - من يستطيع تعديل الجدول يستطيع فتح النص البرمجي وخصائص Script Properties، وقراءة المفتاح، وتشغيل النص البرمجي على رصيدك. - ومن يستطيع عرض الجدول فقط يستطيع أيضًا عرض النص البرمجي وتشغيله، والتشغيل يستخدم مفتاحك. - ومن ينسخ الجدول يحصل على نسخة خاصة به من النص البرمجي، يستطيع تعديلها وتشغيلها. لذلك احتفظ بالنص البرمجي في جدول لا يفتحه أحد غيرك، ولا تمنح أحدًا وصولًا إلى ذلك الملف، ولا حتى صلاحية العرض. ولمشاركة النتائج، انسخ الإجابات إلى جدول آخر قيمًا فقط وشارك ذلك الجدول. وإن ظننت أن المفتاح انكشف، فاتبع [إذا انكشف مفتاح](https://5abeer.ai/ar/docs/account/security.md#leaked). ## كم يكلف؟ تُحاسب كل إجابة بعدد التوكنات في تعليمتك وفي رد النموذج. فمثلًا، 1,000 صف في كل منها نحو 300 توكن إدخال و100 توكن إخراج تساوي 300,000 توكن إدخال و100,000 توكن إخراج على النموذج الافتراضي: مثال: 300,000 توكن إدخال و100,000 توكن إخراج على Claude Sonnet 5.5 (`claude-sonnet-5.5`) تكلّف 0.48 US$ بسعرنا مقابل 1.60 US$ بالسعر الرسمي (أقل بنسبة 70%). آخر مراجعة للسعر الرسمي: 19 أكتوبر 2026. وأرقامك الفعلية تعتمد على تعليماتك والردود. ويستهلك النص العربي غالبًا توكنات أكثر من الإنجليزي للمعنى نفسه، كما في [تكلفة التوكن بالعربي](https://5abeer.ai/ar/guides/arabic-token-cost)، لذلك فإن طلب إجابات قصيرة يخفض التكلفة. وكل نموذج مسعّر بالتوكن أقل من سعره الرسمي، وتعرض [صفحة الـ API](https://5abeer.ai/ar/api) السعرين جنبًا إلى جنب. ## عند ظهور خطأ في الخلية يظهر الخطأ بالشكل `#ERROR!`، فمرّر المؤشر فوق الخلية لتقرأ الرسالة. ومن القائمة تعرض Google الرسالة على الشاشة. وفي أخطاء الـ API تحمل الرسالة رمز الحالة وبداية رد خبير، وفيها رمز الخطأ: | ما تراه | معناه | الحل | | --- | --- | --- | | `Add KHABEER_API_KEY in Project Settings > Script Properties` | خاصية المفتاح غير موجودة | أضف الخاصية كما في خطوة حفظ المفتاح | | `You do not have permission to call …` | ينقص النص البرمجي إذنٌ يحتاج إليه | شغّل 5abeer > Test the key مرة واحدة ووافق على الأذونات | | [`INVALID_API_KEY`](https://5abeer.ai/ar/docs/help/errors.md#INVALID_API_KEY) | المفتاح خاطئ أو نُسخ بمسافات زائدة | انسخ المفتاح مرة أخرى إلى Script Properties | | [`MODEL_PLATFORM_NOT_ALLOWED`](https://5abeer.ai/ar/docs/help/errors.md#MODEL_PLATFORM_NOT_ALLOWED) | المفتاح لنماذج مزوّد آخر | احفظ مفتاحًا لمزوّد النموذج في `MODEL` | | [`INSUFFICIENT_BALANCE`](https://5abeer.ai/ar/docs/help/errors.md#INSUFFICIENT_BALANCE) | رصيدك لا يكفي | اشحن رصيدك | | [`API_KEY_QUOTA_EXHAUSTED`](https://5abeer.ai/ar/docs/help/errors.md#API_KEY_QUOTA_EXHAUSTED) | بلغ المفتاح حد الإنفاق | ارفع الحد من إعدادات المفتاح | | [`API_KEY_EXPIRED`](https://5abeer.ai/ar/docs/help/errors.md#API_KEY_EXPIRED) | تجاوز المفتاح تاريخ انتهائه | أنشئ مفتاحًا جديدًا واحفظه | | [`RATE_LIMITED`](https://5abeer.ai/ar/docs/help/errors.md#RATE_LIMITED) | طلبات كثيرة في وقت واحد | انتظر قليلًا، ثم شغّل القائمة مرة أخرى | | `Exceeded maximum execution time` في خلية الصيغة | استغرقت الإجابة أكثر من 30 ثانية | استخدم القائمة، أو اطلب إجابة أقصر | وكل الرموز وحلولها في [الأخطاء وحلولها](https://5abeer.ai/ar/docs/help/errors.md). ## أسئلة شائعة ### ما النماذج التي يستطيع الجدول استدعاءها؟ نماذج Claude وGPT وGemini، لأن خبير يقدّمها كلها بتنسيق OpenAI، فيبقى الطلب كما هو. غيّر قيمة `MODEL` إلى معرّف النموذج من [صفحة النماذج](https://5abeer.ai/ar/models)، واحفظ مفتاحًا لمزوّد ذلك النموذج في `KHABEER_API_KEY`. وكل مفتاح يغطي مزوّدًا واحدًا، لذلك يشغّل الجدول نماذج مزوّد واحد في كل مرة. ### متى ترسل الصيغة طلبًا جديدًا؟ كلما أُعيد حساب الخلية، مثل تعديل الصيغة أو تغيّر خلية تشير إليها. وكل طلب جديد مدفوع. ولإيقاف ذلك، الصق الإجابات في مكانها قيمًا فقط، أو استخدم القائمة التي تكتب قيمًا ثابتة. ### كم صفًا يجيب عنه تشغيل واحد للقائمة؟ بقدر ما ينتهي خلال حد Google البالغ 6 دقائق لكل تشغيل، وهذا يعتمد على النموذج وطول كل إجابة. شغّل القائمة مرة أخرى لتكمل. وتضع Google أيضًا حدًا لطلبات URL Fetch: 20,000 طلب في اليوم لحساب Google الشخصي، و100,000 طلب في اليوم لحساب Google Workspace، وتقول إن حصصها قد تتغير في أي وقت دون إشعار. ### هل أدفع ثمن الصفوف الفارغة أو التي تخطّاها النص البرمجي؟ لا يُرسل أي طلب لها: فالصيغة لا تعيد شيئًا للخلية الفارغة، والقائمة تتخطى التعليمات الفارغة والصفوف التي فيها إجابة بالفعل. وكل طلب يرسله النص البرمجي فعلًا يُدفع من رصيدك بعدد التوكنات التي يستخدمها، بسعر النموذج في خبير، كما في [الأسعار والرصيد](https://5abeer.ai/ar/docs/start/pricing.md). ### هل مشاركة الجدول آمنة؟ ليس الجدول الذي فيه المفتاح. فمن يعدّله يستطيع قراءة المفتاح في Script Properties، وحتى من يعرضه فقط يستطيع تشغيل النص البرمجي بمفتاحك. انسخ الإجابات إلى جدول آخر قيمًا فقط، وشارك ذلك الجدول. ## المصادر راجعناها في 2026-11-03، في توثيق Google Apps Script: - [UrlFetchApp](https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app) و[URL Fetch Service](https://developers.google.com/apps-script/reference/url-fetch) و[HTTPResponse](https://developers.google.com/apps-script/reference/url-fetch/http-response) - [Custom functions in Google Sheets](https://developers.google.com/apps-script/guides/sheets/functions) و[Custom menus](https://developers.google.com/apps-script/guides/menus) - [Properties Service](https://developers.google.com/apps-script/guides/properties) و[Container-bound scripts](https://developers.google.com/apps-script/guides/bound) و[Authorization for Google services](https://developers.google.com/apps-script/guides/services/authorization) - [Quotas for Google services](https://developers.google.com/apps-script/guides/services/quotas) و[مرجع Range](https://developers.google.com/apps-script/reference/spreadsheet/range) > خبير خدمة مستقلة، ولا تتبع OpenAI أو Anthropic أو Google. ## ابدأ اطّلع على سعر كل نموذج في [صفحة الـ API](https://5abeer.ai/ar/api)، ثم أنشئ مفتاحًا بحد إنفاق لجدولك.