استخدام Excel Power Query API لجلب بيانات Narwhal

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

Power Query هو الطريقة التي يرسل بها Excel طلب API ويقرأ استجابة JSON. ستنتهي باستعلامات للبيانات التي تريدها في المصنف، مثل جدول الإجازات أو سعر Brent الفوري. عمليًا يكون كل مجال استعلامًا مستقلًا. تستخدم الأمثلة عنوان URL الأساسي نفسه وترويسة Authorization نفسها، مع مسار وحقل استجابة مختلفين لكل مجال. ويستخدم Narwhal الحساب نفسه لبياناته الاقتصادية عن CPI والتضخم والناتج المحلي الإجمالي والعوائد.

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

1. أنشئ مفتاحًا مجانيًا أنشئ مفتاحك المجاني من صفحة التسجيل في Narwhal. يغطي حساب واحد ومفتاح API واحد واجهات البيانات المستخدمة هنا. يشترك REST وMCP في هذا المفتاح، وترسله أمثلة Excel مع طلب REST.
2. احتفظ بالمفتاح في متغير بيئة احفظ المفتاح في متغير بيئة اسمه NARWHAL_API_KEY. في أمثلة Power Query M استبدل YOUR_KEY بمفتاحك في ترويسة Authorization. تبدأ قيمة الترويسة بـ Bearer ويتبعها المفتاح.
3. أبقِ المصنف خاصًا يخزّن Power Query المفتاح داخل المصنف لأن ترويسة Authorization موجودة في كود M. استخدم مفتاحًا مجانيًا للجداول ولا تشارك الملف. لا يحل متغير البيئة محل قيمة المفتاح داخل هذه الأمثلة.

افتح استعلامًا فارغًا

1. افتح Get Data ابدأ من علامة التبويب Data وافتح Get Data. ابحث عن From Other Sources ثم Blank Query. هذه هي عناصر التحكم في Power Query المستخدمة لبدء الطلب.
2. افتح المحرر المتقدم افتح الاستعلام الفارغ في المحرر المتقدم والصق كود M من القسم التالي. ضع مفتاحك في الترويسة قبل تحديث الاستعلام.
3. اختر النتيجة المراد إرجاعها يحدد التعبير الذي يلي in نتيجة ذلك الاستعلام. يعيد المثال الكامل Holidays. أعد Releases أو Cpi أو Fx أو Fed للحصول على تلك الجداول، أو Brent لسعر السلعة الفوري. استخدم استعلامًا منفصلًا لكل مجال تريده.

اسحب البيانات بـ Power Query M

أبقِ https://api.narwhalapi.com ثابتًا في Web.Contents. ضع مسار نقطة النهاية في RelativePath ومعاملاتها في Query؛ فهذا يُبقي التحديث يعمل. تقرأ الدالة المساعدة Narwhal استجابة JSON، ويختار كل تعبير حقل مجاله. يسمّي تعبير مواعيد الإصدار أعمدة مخرجاته ويستخدم MissingField.UseNull.

تقبل الدالة المساعدة مسارًا وسجلًا اختياريًا لمعاملات الاستعلام. وعند عدم تمرير سجل استعلام تستخدم سجلًا فارغًا. تعيد Table.FromRecords جداول من مجموعات السجلات، وتتولى Number.FromText سعر Brent. أبقِ اختيار حقل الاستجابة متصلًا باستدعاء المجال الذي تريده.

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ])),
    Holidays = Table.FromRecords(Narwhal("v1/calendars/holidays/USA/2026")[holidays]),
    Releases = Table.FromRecords(
        Narwhal(
            "v1/economics/calendar",
            [countries = "USA", start_date = "2026-11-01",
             end_date = "2026-11-30", limit = "100"]
        )[releases],
        {"at", "period", "topic", "status"}, MissingField.UseNull),
    Cpi = Table.FromRecords(
        Narwhal("v1/economics/USA/cpi/observations", [start = "2025-09"])[observations]
    ),
    Brent = Number.FromText(Narwhal("v1/commodities/spot/BRENT/USD")[price]),
    Fx = Table.FromRecords(Narwhal("v1/fx/rates/USD", [currencies = "EUR,IDR"])[rates]),
    Fed = Table.FromRecords(
        Narwhal("v1/predictions/policy-paths/federal-reserve")[meetings]
    )
in
    // return Releases, Cpi, Fx or Fed the same way;
    // each area is its own query in practice
    Holidays

حدّث المصنف وفق جدول

استخدم Refresh All في علامة التبويب Data لتحديث الاستعلامات. في خصائص الاستعلام اضبط استعلامًا ليُحدَّث عند فتح الملف وكل N دقيقة أثناء فتحه. تنطبق هذه الإعدادات على المصنف المفتوح، لذا أبقِ المصنف مفتوحًا لتعمل التحديثات الدورية.

لا يملك Excel جدولة تعمل في الخلفية. للتشغيل دون إشراف استخدم Power Automate أو سكربتًا خارج Excel. يمكن للاستعلام المضبوط على التحديث عند الفتح أن يسحب البيانات عند فتح الملف مجددًا؛ أما التحديث الدوري فيعتمد على بقاء المصنف مفتوحًا. اضبط خصائص التحديث للاستعلامات التي تريد تحديث بياناتها.

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

اقرأ إجازات الولايات المتحدة الرسمية لعام 2026 من حقل holidays. لكل إجازة date وname، وتحوّل Table.FromRecords السجلات إلى جدول. يعيد هذا المثال جدول الإجازات مباشرةً، بالدالة المساعدة والترويسة نفسيهما في المثال الكامل. استبدل المفتاح قبل استخدامه استعلامًا مستقلًا.

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(Narwhal("v1/calendars/holidays/USA/2026")[holidays])

مواعيد الإصدار في Excel

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

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(
    Narwhal(
        "v1/economics/calendar",
        [countries = "USA", start_date = "2026-11-01",
         end_date = "2026-11-30", limit = "100"]
    )[releases],
    {"at", "period", "topic", "status"},
    MissingField.UseNull
)

البيانات الاقتصادية في Excel

اطلب ملاحظات CPI للولايات المتحدة مع معامل بداية هو سبتمبر 2025. اقرأ observations للحصول على الحقلين period وvalue في جدول. أبقِ الفترة مع قيمة الملاحظة عند استخدام النتيجة في المصنف. وأبقِ معامل البداية في Query كما في المثال الكامل.

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(
    Narwhal("v1/economics/USA/cpi/observations", [start = "2025-09"])[observations]
)

أسعار السلع الفورية في Excel

اقرأ سعر Brent الفوري بالدولار الأمريكي من price. حقل الاستجابة هذا سعر، ويستخدم تعبير M الدالة Number.FromText لإعادته رقمًا. تشمل رموز الأسعار الفورية للسلع على سبيل المثال XAU وXAG وXPT وXPD وXCU وBRENT وWTI. يستخدم هذا المثال BRENT.

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Number.FromText(Narwhal("v1/commodities/spot/BRENT/USD")[price])

أسعار الصرف في Excel

استخدم USD عملةً أساسية واطلب EUR وIDR في المعامل currencies. اختر rates من الاستجابة وحوّل السجلات إلى جدول. لكل سجل currency وrate، فتبقى العملة بجانب سعرها في نتيجة الاستعلام.

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(Narwhal("v1/fx/rates/USD", [currencies = "EUR,IDR"])[rates])

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

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

let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(Narwhal("v1/predictions/policy-paths/federal-reserve")[meetings])

لماذا يطلب Power Query بيانات اعتماد؟

اختر المصادقة المجهولة (Anonymous) لمصدر الويب. يسمح Power Query بترويسة Authorization مع المصادقة المجهولة فقط. وما يزال الطلب يرسل مفتاح Narwhal في الترويسة من كود M؛ أما خيار بيانات اعتماد مصدر الويب فهو Anonymous.

هل يمكنني استخدام NETWORKDAYS مع النتيجة؟

نعم. اجعل وسيط العطلات في NETWORKDAYS يشير إلى عمود date في جدول Holidays. استخدم تواريخ الإجازات التي أعادها الاستعلام لهذا الوسيط؛ أما عمود name فيحتوي على أسماء الإجازات. يطلب مثال إجازات الولايات المتحدة عام 2026، فتواريخه هي إجازات تلك السنة. استخدم هذه النتيجة في الحسابات التي تحتاج إلى تواريخ الإجازات هذه.