استخدام API في Google Sheets مع Narwhal

ما الذي ستعدّه

يربط Apps Script جدول البيانات بالواجهة عبر UrlFetchApp. ستحصل على علامة تبويب لكل مجال بيانات ودالة pullAll تملؤها بمفتاح API نفسه. يبقى المفتاح في خصائص السكربت (Script properties)، ويقرؤه السكربت عند إرسال كل طلب. يشترك REST وMCP في هذا المفتاح عبر واجهات البيانات. عنوان URL الأساسي هو https://api.narwhalapi.com، ويستخدم كل استدعاء للبيانات الطريقة GET.

اضبط مفتاح API الخاص بك

1. أنشئ مفتاحًا مجانيًا احصل على مفتاح Narwhal API مجاني. احتفظ بالمفتاح لخاصية السكربت التي ستضيفها في المحرر، ولا تضعه أبدًا في خلية من خلايا الجدول.
2. افتح Apps Script في Google Sheets افتح قائمة Extensions واختر Apps Script. هنا ستضيف السكربت وتهيّئ وصوله إلى مفتاحك.
3. احفظ المفتاح في خصائص السكربت في Project Settings أضف خاصية سكربت باسم NARWHAL_API_KEY واجعل قيمتها مفتاحك. يقرؤها السكربت بـ PropertiesService.getScriptProperties() ويرسلها في ترويسة Authorization بالصيغة Bearer YOUR_KEY.

اسحب البيانات بـ Apps Script

1. أنشئ علامات تبويب البيانات أنشئ علامات تبويب بالأسماء Holidays وReleases وCPI وBrent وFX وFed. أبقِ هذه الأسماء كما هي تمامًا لأن السكربت يستخدمها لإيجاد وجهة كل استجابة.
2. أضف السكربت الصق هذا الكود في Apps Script. تقرأ الدالة المساعدة المشتركة pull حقل الاستجابة المسمى في كل استدعاء وتكتب صفوفه في علامة التبويب المطابقة. يستخدم Brent كائن الاستجابة مباشرةً لأن سعره خارج أي قائمة.
   Apps Script: ستة مجالات

   const API = "https://api.narwhalapi.com";
   
   function pull(sheetName, path, listKey) {
     const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
     const res = UrlFetchApp.fetch(API + path, {
       headers: { Authorization: "Bearer " + key },
     });
     const body = JSON.parse(res.getContentText());
     const rows = listKey ? body[listKey] : [body];
     if (!rows || rows.length === 0) return; // an empty list writes nothing
     const columns = [];
     rows.forEach((row) =>
       Object.keys(row).forEach((name) => {
         // every row, so a null first value cannot hide a column
         if (
           !columns.includes(name) &&
           (row[name] === null || typeof row[name] !== "object")
         )
           columns.push(name);
       }),
     );
     const values = [columns].concat(
       rows.map((row) =>
         columns.map((name) =>
           row[name] === undefined || row[name] === null ? "" : row[name],
         ),
       ),
     );
     const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(sheetName);
     sheet.clear();
     // Text columns (dates, periods like 2026-09) stay plain text so Sheets does not
     // turn them into dates.
     // Decimal strings such as "1.0823" stay numbers.
     columns.forEach((name, index) => {
       const sample = rows.find(
         (row) => typeof row[name] === "string" && row[name] !== "",
       );
       if (sample && !/^-?\d+(\.\d+)?$/.test(sample[name]))
         sheet.getRange(1, index + 1, values.length, 1).setNumberFormat("@");
     });
     sheet.getRange(1, 1, values.length, columns.length).setValues(values);
   }
   
   function pullAll() {
     pull("Holidays", "/v1/calendars/holidays/USA/2026", "holidays");
     pull(
       "Releases",
       "/v1/economics/calendar?countries=USA&start_date=2026-11-01" +
         "&end_date=2026-11-30&limit=100",
       "releases",
     );
     pull("CPI", "/v1/economics/USA/cpi/observations?start=2025-09", "observations");
     pull("Brent", "/v1/commodities/spot/BRENT/USD", null);
     pull("FX", "/v1/fx/rates/USD?currencies=EUR,IDR", "rates");
     pull("Fed", "/v1/predictions/policy-paths/federal-reserve", "meetings");
   }

3. شغّل pullAll شغّل pullAll من المحرر لملء علامات التبويب. في حالة الاستجابة غير الفارغة تمسح الدالة المساعدة علامة تبويب الوجهة وتكتب صف العناوين متبوعًا بالبيانات، لذا أبقِ الصيغ خارج هذه العلامات. لا تكتب القوائم الفارغة شيئًا. وتقرأ أسماء الأعمدة من كل الصفوف، فلا تخفي قيمة أولى null أي عمود.

تبقى أعمدة النص، ومنها التواريخ والفترات مثل 2026-09، نصًا عاديًا حتى لا يحوّلها Sheets إلى تواريخ. وتبقى القيم العشرية المرسلة كسلاسل نصية، مثل 1.0823، أرقامًا. تستخدم الاستدعاءات أدناه الدالة المساعدة وعنوان URL الأساسي لـ API وخاصية السكربت نفسها؛ ويحدد كل منها علامة تبويب الوجهة ومسار الطلب وحقل الاستجابة.

شغّله وفق جدول

1. افتح المشغّلات استخدم أيقونة الساعة في محرر Apps Script لفتح المشغّلات.
2. أضف مشغّلًا زمنيًا أضف مشغّلًا زمنيًا لـ pullAll، مثلًا يوميًا. وهو يستدعي الدالة نفسها التي تملأ علامات تبويب البيانات من المحرر.

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

الإجازات الرسمية في Google Sheets

اسحب إجازات الولايات المتحدة الرسمية لعام 2026 إلى Holidays. قائمة الاستجابة هي holidays، ولكل عنصر date وname. تكتب الدالة المساعدة الحقلين عمودين وتُبقي نص التاريخ كما هو. استخدم هذا الاستدعاء مع السكربت المشترك عندما تريد صفوف الإجازات في علامة تبويب خاصة بها.

pull(
  "Holidays", "/v1/calendars/holidays/USA/2026", "holidays"
);
// Read date and name in the Holidays tab.

مواعيد الإصدار في Google Sheets

اسحب تقويم إصدارات البيانات الاقتصادية للولايات المتحدة لشهر نوفمبر 2026 إلى Releases. اقرأ releases من الاستجابة، ولكل عنصر at وperiod وtopic وstatus. هذا الطلب مخصص لمواعيد الإصدار؛ استخدم استدعاء ملاحظات CPI للقيم الاقتصادية المرتبطة بالفترات.

pull(
  "Releases",
  "/v1/economics/calendar?countries=USA&start_date=2026-11-01" +
    "&end_date=2026-11-30&limit=100",
  "releases",
);
// Read at, period, topic and status in the Releases tab.

البيانات الاقتصادية في Google Sheets

اسحب ملاحظات CPI للولايات المتحدة إلى CPI مع بداية مطلوبة في سبتمبر 2025. قائمة الاستجابة هي observations، وأعمدة علامة التبويب هي period وvalue. اقرأ صف العناوين بعد أول عملية سحب. وفي الحسابات الشهرية ابحث عن كل شهر بنص الفترة حتى لا يؤدي غياب شهر إلى إزاحة الصيغة.

pull(
  "CPI", "/v1/economics/USA/cpi/observations?start=2025-09", "observations"
);
// Read period and value in the CPI tab.

لمقارنة سبتمبر 2026 بأغسطس 2026 استخدم الصيغة أدناه خارج علامة تبويب CPI. يبحث كل VLOOKUP عن الشهر المسمى في CPI!A:B؛ ويقسم الحساب قيمة سبتمبر على قيمة أغسطس ثم يطرح واحدًا.

=VLOOKUP("2026-09",CPI!A:B,2,FALSE)/VLOOKUP("2026-08",CPI!A:B,2,FALSE)-1

أسعار السلع الفورية في Google Sheets

اسحب سعر Brent الفوري بالدولار الأمريكي إلى Brent. اقرأ حقل price من كائن الاستجابة. يمرّر هذا الاستدعاء null مفتاحًا للقائمة، فتعامل الدالة المساعدة الكائن كله صفًّا واحدًا وتكتب حقوله تحت أسماء الأعمدة.

pull(
  "Brent", "/v1/commodities/spot/BRENT/USD", null
);
// Read price in the Brent tab.

أسعار الصرف في Google Sheets

اسحب أسعار صرف EUR وIDR مع USD عملةً أساسية إلى FX. في قائمة rates لكل عنصر currency وrate. أبقِ هذين العمودين معًا عند قراءة علامة التبويب حتى يظل كل سعر مرتبطًا بعملته.

pull(
  "FX", "/v1/fx/rates/USD?currencies=EUR,IDR", "rates"
);
// Read currency and rate in the FX tab.

احتمالات أسواق التنبؤ في Google Sheets

اسحب مسار سياسة الاحتياطي الفيدرالي إلى Fed. قائمة الاستجابة هي meetings، ولكل عنصر resolves_at وp_cut وp_hold وp_hike. اقرأ وقت الحسم مع الاحتمالات حتى تبقى حقول الخفض والتثبيت والرفع مرتبطة باجتماعها.

pull(
  "Fed", "/v1/predictions/policy-paths/federal-reserve", "meetings"
);
// Read resolves_at, p_cut, p_hold and p_hike in the Fed tab.

لماذا لا أستخدم IMPORTDATA أو IMPORTXML؟

لا يستطيع IMPORTDATA وIMPORTXML إرسال ترويسة Authorization. تتطلب طلبات Narwhal API ترويسة Bearer، لذا استخدم Apps Script مع UrlFetchApp لإرسال الطلب. تقرأ الدالة المساعدة المفتاح من خصائص السكربت وتضيف الترويسة قبل جلب الاستجابة.

هل يمكنني استخدام NETWORKDAYS مع بيانات الإجازات؟

نعم. استخدم عمود date في علامة تبويب Holidays وسيطًا للإجازات في NETWORKDAYS. استخدم تواريخ ذلك العمود وليس أسماء الإجازات. يوفّر طلب الإجازات في هذا السكربت تواريخ إجازات الولايات المتحدة لعام 2026.

لماذا قد تبدأ استجابة CPI بعد الفترة المطلوبة؟

يقرأ كل حساب السجل الكامل. إذا بدأت السلسلة بعد تاريخ البداية المطلوب، تبدأ الاستجابة من أول رصد لها.