ربط Google Sheets بالذكاء الاصطناعي: استدعِ نموذجًا من خلية

لتستدعي نموذج ذكاء اصطناعي من 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، كما في ما هو العنوان الأساسي؟. متوافق مع OpenAI: غيّر العنوان الأساسي واحتفظ بالكود نفسه.

وكل إجابة طلب واحد مثل هذا:

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":"اكتب فكرة منتج في سطر واحد"}]}'

{
  "id": "chatcmpl-9f2",
  "object": "chat.completion",
  "model": "claude-sonnet-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "مرحبًا! كيف أساعدك اليوم؟"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 12,
    "total_tokens": 33
  }
}

ويتيح لك النص البرمجي طريقتين لتشغيله:

قبل أن تبدأ#

تحتاج إلى مفتاح API من خبير لمزوّد النموذج الذي يستدعيه النص البرمجي. ويعمل كل مفتاح مع نماذج مزوّد واحد، والنص البرمجي يستدعي claude-sonnet-5.5، لذلك أنشئ مفتاحًا لنماذج Claude كما في إنشاء مفتاح.

تحكّم في كل مفتاح: حد للإنفاق، وتاريخ انتهاء، وقائمة عناوين IP المسموح بها. وخصّص لهذا الجدول مفتاحًا خاصًا به، بحد إنفاق وتاريخ انتهاء، كما في تحكّم في كل مفتاح، حتى لا يكلفك أي خطأ في الجدول إلا القليل. ولا تقصر هذا المفتاح على عنوان IP الخاص بك، لأن Apps Script يرسل طلباته من خوادم Google لا من جهازك، فيرفض المفتاح عندها كل طلبات الجدول.

أضف النص البرمجي#

1. 1

   افتح Apps Script#

   في جدولك، اختر Extensions > Apps Script. فيُفتح مشروع نص برمجي مرتبط بالجدول، فيه ملف اسمه Code.gs.

2. 2

   احفظ المفتاح#

   في محرر Apps Script، افتح Project Settings، ثم أضف تحت Script Properties خاصية اسمها KHABEER_API_KEY وقيمتها مفتاحك من خبير، واحفظ. بهذا يبقى المفتاح خارج الكود وخارج الخلايا.

3. 3

   الصق الكود#

   استبدل كل ما في Code.gs بهذا الكود، ثم احفظ:

   Code.gsانسخ

   // 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 إلى معرّفه من صفحة النماذج، واحفظ مفتاحًا لمزوّد ذلك النموذج. ويمكنك أن تكتب أسماء القائمة بالعربية مثلًا، بتغييرها في الدالة onOpen.

4. 4

   اختبر المفتاح#

   أعد تحميل الجدول، فتظهر قائمة 5abeer في شريط القوائم. اختر 5abeer > Test the key، ووافق على الأذونات التي تطلبها Google في أول تشغيل. وظهور نافذة فيها رد النموذج يعني أن الإعداد يعمل. ويرسل هذا الاختبار طلبًا صغيرًا واحدًا مدفوعًا.

استخدمه في خلية#

اكتب الصيغة في خلية، ومعها تعليمتك ومرجع الخلية:

=ASK_AI("Summarize in one sentence: " & A2)

ويمكنك أن تكتب التعليمة بالعربية أيضًا. ونفّذ خطوة اختبار المفتاح أولًا: فالصيغة لا تطلب الأذونات أبدًا، لذلك توافق عليها مرة واحدة من القائمة. ثم اسحب الصيغة إلى الأسفل لتعمل في كل صف. وكل خلية طلب مدفوع مستقل، وترسل طلبًا جديدًا كلما أُعيد حسابها. وللاحتفاظ بالإجابات وإيقاف الطلبات الجديدة، انسخ الخلايا والصقها في مكانها قيمًا فقط. ويجب أن تصل إجابة الخلية خلال 30 ثانية، وإلا ظهر فيها #ERROR!. كما يجري Sheets استدعاءً منفصلًا لكل خلية فيها الصيغة، فيصبح بطيئًا مع مئات الصفوف. وللإجابات الطويلة أو الصفوف الكثيرة، استخدم القائمة.

املأ عمودًا من القائمة#

حدّد الخلايا التي فيها تعليماتك، في عمود واحد، ثم اختر 5abeer > Answer the selected cells. فتُكتب الإجابات في العمود التالي قيمًا ثابتة، فلا ترسل أي طلب بعد ذلك.

ويتخطى النص البرمجي الخلايا الفارغة والصفوف التي فيها إجابة بالفعل، ويحفظ كل إجابة عند وصولها. وتوقف Google التشغيل بعد 6 دقائق، فإذا كان العمود طويلًا، شغّل القائمة مرة أخرى لتكمل من أول صف بلا إجابة. وأي رد يبدأ بالرمز = أو + أو - أو @ يُحفظ نصًا، فلا يتحول إلى صيغة أبدًا.

احمِ المفتاح#

النص البرمجي المرتبط بجدول يتبع قائمة الوصول نفسها التي للجدول، وخصائص Script Properties واحدة لكل من يشغّل النص البرمجي:

• من يستطيع تعديل الجدول يستطيع فتح النص البرمجي وخصائص Script Properties، وقراءة المفتاح، وتشغيل النص البرمجي على رصيدك.
• ومن يستطيع عرض الجدول فقط يستطيع أيضًا عرض النص البرمجي وتشغيله، والتشغيل يستخدم مفتاحك.
• ومن ينسخ الجدول يحصل على نسخة خاصة به من النص البرمجي، يستطيع تعديلها وتشغيلها.

لذلك احتفظ بالنص البرمجي في جدول لا يفتحه أحد غيرك، ولا تمنح أحدًا وصولًا إلى ذلك الملف، ولا حتى صلاحية العرض. ولمشاركة النتائج، انسخ الإجابات إلى جدول آخر قيمًا فقط وشارك ذلك الجدول. وإن ظننت أن المفتاح انكشف، فاتبع إذا انكشف مفتاح.

كم يكلف؟#

تُحاسب كل إجابة بعدد التوكنات في تعليمتك وفي رد النموذج. فمثلًا، 1,000 صف في كل منها نحو 300 توكن إدخال و100 توكن إخراج تساوي 300,000 توكن إدخال و100,000 توكن إخراج على النموذج الافتراضي:

وأرقامك الفعلية تعتمد على تعليماتك والردود. ويستهلك النص العربي غالبًا توكنات أكثر من الإنجليزي للمعنى نفسه، كما في تكلفة التوكن بالعربي، لذلك فإن طلب إجابات قصيرة يخفض التكلفة. وكل نموذج مسعّر بالتوكن أقل من سعره الرسمي، وتعرض صفحة الـ API السعرين جنبًا إلى جنب.

عند ظهور خطأ#

في الخلية يظهر الخطأ بالشكل #ERROR!، فمرّر المؤشر فوق الخلية لتقرأ الرسالة. ومن القائمة تعرض Google الرسالة على الشاشة. وفي أخطاء الـ API تحمل الرسالة رمز الحالة وبداية رد خبير، وفيها رمز الخطأ:

وكل الرموز وحلولها في الأخطاء وحلولها.

أسئلة شائعة#

ما النماذج التي يستطيع الجدول استدعاءها؟#

نماذج Claude وGPT وGemini، لأن خبير يقدّمها كلها بتنسيق OpenAI، فيبقى الطلب كما هو. غيّر قيمة MODEL إلى معرّف النموذج من صفحة النماذج، واحفظ مفتاحًا لمزوّد ذلك النموذج في KHABEER_API_KEY. وكل مفتاح يغطي مزوّدًا واحدًا، لذلك يشغّل الجدول نماذج مزوّد واحد في كل مرة.

متى ترسل الصيغة طلبًا جديدًا؟#

كلما أُعيد حساب الخلية، مثل تعديل الصيغة أو تغيّر خلية تشير إليها. وكل طلب جديد مدفوع. ولإيقاف ذلك، الصق الإجابات في مكانها قيمًا فقط، أو استخدم القائمة التي تكتب قيمًا ثابتة.

كم صفًا يجيب عنه تشغيل واحد للقائمة؟#

بقدر ما ينتهي خلال حد Google البالغ 6 دقائق لكل تشغيل، وهذا يعتمد على النموذج وطول كل إجابة. شغّل القائمة مرة أخرى لتكمل. وتضع Google أيضًا حدًا لطلبات URL Fetch: ‏20,000 طلب في اليوم لحساب Google الشخصي، و100,000 طلب في اليوم لحساب Google Workspace، وتقول إن حصصها قد تتغير في أي وقت دون إشعار.

هل أدفع ثمن الصفوف الفارغة أو التي تخطّاها النص البرمجي؟#

لا يُرسل أي طلب لها: فالصيغة لا تعيد شيئًا للخلية الفارغة، والقائمة تتخطى التعليمات الفارغة والصفوف التي فيها إجابة بالفعل. وكل طلب يرسله النص البرمجي فعلًا يُدفع من رصيدك بعدد التوكنات التي يستخدمها، بسعر النموذج في خبير، كما في الأسعار والرصيد.

هل مشاركة الجدول آمنة؟#

ليس الجدول الذي فيه المفتاح. فمن يعدّله يستطيع قراءة المفتاح في Script Properties، وحتى من يعرضه فقط يستطيع تشغيل النص البرمجي بمفتاحك. انسخ الإجابات إلى جدول آخر قيمًا فقط، وشارك ذلك الجدول.

المصادر#

راجعناها في 2026-11-03، في توثيق Google Apps Script:

• UrlFetchApp وURL Fetch Service وHTTPResponse
• Custom functions in Google Sheets وCustom menus
• Properties Service وContainer-bound scripts وAuthorization for Google services
• Quotas for Google services ومرجع Range

ابدأ#

اطّلع على سعر كل نموذج في صفحة الـ API، ثم أنشئ مفتاحًا بحد إنفاق لجدولك.