كيفية سحب بيانات الماكرو إلى Excel / Google Sheets

تبقى جداول البيانات الأداة الأكثر شيوعًا لتحليل الكلي. سواء كنت تفضل Excel أو Google Sheets ، فإن سحب بيانات البنك المركزي والمعيار الاقتصادي المباشرة مباشرة إلى خلية بدلاً من نسخ القيم يدويًا يحول الجدول الثابت إلى مساعد قرار تحديث ذاتي. يوضح لك هذا الدليل كيفية توصيل FXMacroData إلى كلا المنصتين: Power Query و VBA لـ Excel ، و Apps Script لـ Google Sheet. بحلول النهاية ، سيتم تحديث كل رقم كلي تهتم به تلقائيًا دون مغادرة جدول البياناتك.

الجزء 1 Excel

يقدم Excel طريقتين لبيانات API الحية: استفسار الطاقة (لا يوجد رمز، عظيم للمحللين) و VBA (محرك بالرمز، أفضل عندما تحتاج إلى كتابة القيم في خلايى محددة أو إطلاق المنطق من زر أو حدث).

الخطوة 1 فهم شكل نقطة نهاية واجهة برمجة التطبيقات

كل مؤشر FXMacroData يتبع نفس نمط REST. يبدو طلب سعر الفائدة الأمريكي على هذا النحو:

GET https://fxmacrodata.com/api/v1/announcements/usd/policy_rate?api_key=YOUR_API_KEY&start=2020-01-01

استجابة JSON هي كائن مسطح مع data صف:

{
  "data": [
    { "date": "2025-03-19", "val": 4.25, "announcement_datetime": "2025-03-19T18:00:00Z" },
    { "date": "2025-01-29", "val": 4.25, "announcement_datetime": "2025-01-29T19:00:00Z" },
    { "date": "2024-12-18", "val": 4.25, "announcement_datetime": "2024-12-18T19:00:00Z" }
  ]
}

كل سجل يحمل date (سنة سنة-ميلاد-ميا) ، رقم val، و عند توفر مستوى UTC الثاني announcement_datetime. لأن كل نقطة نهاية مؤشر تتشارك هذا الشكل، وظيفة Power Query واحدة أو مساعد VBA واحد يمكن أن تخدم كل منهم. استكشاف الكتالوج كامل المؤشر في مستندات API.

الخطوة 2 Excel Power Query: استيراد عبر رابط الويب

"مستعرض الطاقة" مدمج من موقع الويب يمكن أن يستهلك أي نقطة نهاية REST JSON بدون رمز على الإطلاق.

1. في Excel، انقر على البيانات → الحصول على البيانة من مصادر أخرى من الويب.
2. إلصق عنوان URL الخاص بك في مربع الحوار YOUR_API_KEY مع مفتاحك الحقيقي:
   https://fxmacrodata.com/api/v1/announcements/usd/policy_rate?api_key=YOUR_API_KEY&start=2020-01-01
3. انقر حسناً. يفتح Power Query Navigator مع إظهار بنية JSON
4. انقر على البيانات سجل في الملاحة لتوسيعه، ثم انقر على تحويل إلى الجدول ! حسناً.
5. استخدم توسيع العمود زر (رمز الأسهم المزدوجة) على Column1 الرأس لفك سجلات التجميع في أعمدة مسطحة: date- لا val- لا announcement_datetime.
6. انقر إغلاق و تحميل لكى تكتب الجدول فى ورقة جديدة

الخطوة 3 Excel Power Query: تعيين المعايير مع وظيفة قابلة لإعادة الاستخدام

بمجرد أن يكون لديك استفسار مؤشر واحد يعمل، وتعزيزها إلى وظيفة M قابلة لإعادة الاستخدام حتى تتمكن من سحب أي عملة / مزيج مؤشر دون تكرار خطوات رابط الويب.

1. في محرر الاستعلامات، انقر بزر الماوس الأيمن على استفسارك في اللوحة اليسرى → إنشاء وظيفة. .
2. أسميه FetchMacroData. .
3. استبدال جسمها بشفرة M أدناه:

// FetchMacroData — reusable Power Query function
// Parameters: currency (e.g. "usd"), indicator (e.g. "policy_rate"), apiKey, startDate
(currency as text, indicator as text, apiKey as text, startDate as text) =>
let
    url     = "https://fxmacrodata.com/api/v1/announcements/"
              & currency & "/" & indicator
              & "?api_key=" & apiKey
              & "&start=" & startDate,
    raw     = Json.Document(Web.Contents(url)),
    records = raw[data],
    tbl     = Table.FromList(records, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expand  = Table.ExpandRecordColumn(tbl, "Column1",
                {"date", "val", "announcement_datetime"},
                {"Date", "Value", "AnnouncementDatetime"}),
    typed   = Table.TransformColumnTypes(expand, {
                {"Date",  type date},
                {"Value", type number}
              })
in
    typed

4. أغلق محرر الوظائف و الآن اصنع وظيفة جديدة استفسار فارغ لكل مؤشر تحتاج إليه:

= FetchMacroData("usd", "inflation", "YOUR_API_KEY", "2022-01-01")

= FetchMacroData("eur", "policy_rate", "YOUR_API_KEY", "2022-01-01")

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

الخطوة 4 Excel VBA: كتابة القيم مباشرة في الخلايا

VBA مناسبة بشكل أفضل عندما تحتاج إلى وضع القيم في خلايى محددة تحمل أسماء، أو ربطها بالصيغ الموجودة، أو تشغيل التحديث من زر أو حدث مفتوح في المجلد.

افتح محرر VBA (Alt+F11), إدخال وحدة جديدة (إدراج → وحدة) واصطفأ ما يلي:

Option Explicit

' ─────────────────────────────────────────────────────────────────
' FetchLatestIndicator
' Returns the most recent val for a given currency/indicator.
' Requires a reference to "Microsoft XML, v6.0" (VBA Editor →
' Tools → References → tick "Microsoft XML, v6.0").
' ─────────────────────────────────────────────────────────────────
Function FetchLatestIndicator(currency As String, indicator As String, _
                               apiKey As String) As Variant
    Dim http     As New MSXML2.XMLHTTP60
    Dim url      As String
    Dim json     As String
    Dim dataArr  As Variant
    Dim parsed   As Object

    url = "https://fxmacrodata.com/api/v1/announcements/" & _
          LCase(currency) & "/" & LCase(indicator) & _
          "?api_key=" & apiKey & "&limit=1"

    http.Open "GET", url, False
    http.setRequestHeader "Accept", "application/json"
    http.Send

    If http.Status <> 200 Then
        FetchLatestIndicator = CVErr(xlErrValue)
        Exit Function
    End If

    ' ── Minimal JSON parser (no external library needed) ──────────
    ' Locate the first "val": number pattern after "data":[{
    Dim pos     As Long
    Dim valStr  As String
    json = http.responseText
    pos  = InStr(json, """val"":")
    If pos = 0 Then
        FetchLatestIndicator = CVErr(xlErrNA)
        Exit Function
    End If
    pos    = pos + Len("""val"":")
    valStr = Mid(json, pos, 20)
    ' Trim to the actual number (stop at comma, space, or brace)
    valStr = Split(Trim(valStr), ",")(0)
    valStr = Split(valStr, "}")(0)
    valStr = Trim(valStr)
    FetchLatestIndicator = CDbl(valStr)
End Function


' ─────────────────────────────────────────────────────────────────
' RefreshMacroDashboard
' Writes the latest value of several indicators into named cells.
' Define Named Ranges (Formulas → Name Manager) matching the keys
' used in the pairs array below.
' ─────────────────────────────────────────────────────────────────
Sub RefreshMacroDashboard()
    Dim apiKey As String
    apiKey = "YOUR_API_KEY"   ' ← replace with your key

    Dim pairs(5, 1) As String
    pairs(0, 0) = "usd" : pairs(0, 1) = "policy_rate"
    pairs(1, 0) = "eur" : pairs(1, 1) = "policy_rate"
    pairs(2, 0) = "gbp" : pairs(2, 1) = "policy_rate"
    pairs(3, 0) = "usd" : pairs(3, 1) = "inflation"
    pairs(4, 0) = "usd" : pairs(4, 1) = "unemployment"
    pairs(5, 0) = "usd" : pairs(5, 1) = "gdp"

    Dim i   As Integer
    Dim val As Variant
    Dim nm  As String
    For i = 0 To 5
        val = FetchLatestIndicator(pairs(i, 0), pairs(i, 1), apiKey)
        nm  = UCase(pairs(i, 0)) & "_" & pairs(i, 1)
        On Error Resume Next
        ThisWorkbook.Names(nm).RefersToRange.Value = val
        On Error GoTo 0
    Next i

    MsgBox "Dashboard updated — " & Now(), vbInformation, "FXMacroData"
End Sub

الجزء الثاني صفحات جوجل

Google Apps Script هو وقت تشغيل JavaScript مدمج مباشرة في Google Workspace. إنه يعمل على جانب الخادم على بنية تحتية Google ، لذلك لا يوجد شيء لتثبيته. يمكنك استدعاء FXMacroData عبر UrlFetchApp وكتب النتائج إلى جدول البيانات مع SpreadsheetApp. أجهزة إطلاق مدفوعة بالوقت تسمح لك بجدولة تحديثات تلقائية

الخطوة 5 افتح محرر البرامج

1. افتح sheets.google.com وخلق جدول بيانات جديد فارغ
2. انقر الإضافات → البرامج النصية. .
3. أعد تسمية المشروع إلى محمول FXMacroData (المنطقة العلوية اليسرى)
4. حذف الافتراضية myFunction() مكان الحجز

الخطوة 6 اكتب مساعد البحث وكاتب الورق

اضغط على الرمز التالي Code.gs.المهام الثلاث تتعامل مع الاسترداد، التطبيع، والكتابة:

// ── Config ──────────────────────────────────────────────────────
const BASE_URL = 'https://fxmacrodata.com/api/v1';

// List of {currency, indicator} pairs to load.
// Add or remove rows to customise your dashboard.
const INDICATORS = [
  { currency: 'usd', indicator: 'policy_rate'  },
  { currency: 'usd', indicator: 'inflation'    },
  { currency: 'usd', indicator: 'unemployment' },
  { currency: 'eur', indicator: 'policy_rate'  },
  { currency: 'gbp', indicator: 'policy_rate'  },
  { currency: 'aud', indicator: 'policy_rate'  },
];


// ── Fetch helper with retry ─────────────────────────────────────
/**
 * Fetches the latest N records for a currency/indicator pair.
 * Retries up to maxRetries times with exponential back-off.
 *
 * @param {string} currency   - e.g. 'usd'
 * @param {string} indicator  - e.g. 'policy_rate'
 * @param {string} apiKey
 * @param {number} limit      - number of records to return (default 12)
 * @param {number} maxRetries
 * @returns {Array} array of {date, val, announcement_datetime} objects
 */
function fetchIndicator(currency, indicator, apiKey, limit = 12, maxRetries = 3) {
  const url = `${BASE_URL}/announcements/${currency}/${indicator}`
            + `?api_key=${apiKey}&limit=${limit}`;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const resp = UrlFetchApp.fetch(url, { muteHttpExceptions: true });
      if (resp.getResponseCode() === 200) {
        return JSON.parse(resp.getContentText()).data || [];
      }
    } catch (e) {
      if (attempt < maxRetries - 1) {
        Utilities.sleep(Math.pow(2, attempt) * 1000); // 1 s, 2 s, 4 s
      }
    }
  }
  return [];
}


// ── Sheet writer ────────────────────────────────────────────────
/**
 * Writes all indicator rows to a sheet named 'MacroData'.
 * Creates the sheet if it does not exist; clears it on each run
 * so stale rows are removed.
 */
function refreshMacroData() {
  const apiKey = PropertiesService.getScriptProperties()
                                  .getProperty('FXMACRODATA_API_KEY');
  if (!apiKey) {
    throw new Error('FXMACRODATA_API_KEY script property is not set.');
  }

  const ss        = SpreadsheetApp.getActiveSpreadsheet();
  let   sheet     = ss.getSheetByName('MacroData');
  if (!sheet) {
    sheet = ss.insertSheet('MacroData');
  }
  sheet.clearContents();

  // Header row
  const headers = ['Currency', 'Indicator', 'Date', 'Value', 'AnnouncementDatetime'];
  sheet.appendRow(headers);

  // Style header
  const headerRange = sheet.getRange(1, 1, 1, headers.length);
  headerRange.setBackground('#1e3a5f');
  headerRange.setFontColor('#ffffff');
  headerRange.setFontWeight('bold');

  // Data rows
  INDICATORS.forEach(({ currency, indicator }) => {
    const records = fetchIndicator(currency, indicator, apiKey);
    records.forEach(r => {
      sheet.appendRow([
        currency.toUpperCase(),
        indicator,
        r.date,
        r.val,
        r.announcement_datetime || ''
      ]);
    });
  });

  // Auto-resize columns for readability
  sheet.autoResizeColumns(1, headers.length);
}

الخطوة 7 تشغيل وتحقق

1. انقر على حفظ رمز (قرص موصل) في شريط أدوات المحرر.
2. اختر refreshMacroData في الوظيفة المنسدلة بجانب زر التشغيل (▶).
3. انقر إهرب. يطلب التشغيل الأول الإذن بالوصول إلى جدول البيانات وإجراء طلبات HTTP خارجية انقر مراجعة الأذونات → السماح. .
4. عودوا إلى جدول البيانات، علامة تبويب جديدة تسمى البيانات الكبيرة يجب أن تحتوي الآن على صفوف مثل:

الخطوة 8 جدولة تحديث تلقائي مع محرك

إطلاق مدفوع بالزمن refreshMacroData على جدول بدون أي عمل يدوي

1. في محرر البرامج النصية، انقر على أسباب رمز (الساعة) في الشريط الجانبي الأيسر.
2. انقر + إضافة محرك (أسفل اليمين)
3. - تمّ تعيينها اختر أي وظيفة تشغيل ! refreshMacroData. .
4. - تمّ تعيينها حدد مصدر الحدث ! مدفوعة بالوقت. .
5. - تمّ تعيينها حدد نوع التشغيل القائم على الوقت ! عداد التوقيت النهاري. .
6. - تمّ تعيينها حدد وقت اليوم → على سبيل المثال الساعة 7 صباحاً 8 صباحا (قبل المسابقة الأوروبية المفتوحة).
7. انقر حفظ. يظهر الزناد في قائمة الزناد.

الخطوة 9 سحب أحدث قيمة في أي خلية مع وظيفة مخصصة

أضف الدالة أدناه إلى Code.gs إذا كنت تريد الإشارة إلى قيم الماكرو مباشرة في صيغ الخلية مثل GOOGLEFINANCE() ولكن بالنسبة لبيانات البنك المركزي:

/**
 * Custom Sheets function: returns the latest value for a currency/indicator.
 *
 * Usage in a cell:  =FXMD("usd","policy_rate")
 *
 * @param {string} currency   e.g. "usd"
 * @param {string} indicator  e.g. "policy_rate"
 * @customfunction
 */
function FXMD(currency, indicator) {
  const apiKey  = PropertiesService.getScriptProperties()
                                   .getProperty('FXMACRODATA_API_KEY');
  const records = fetchIndicator(currency, indicator, apiKey, 1);
  if (!records || records.length === 0) return null;
  return records[0].val;
}

بعد حفظ، اكتب =FXMD("usd","policy_rate") في أي خلية. أوراق تدعو الدالة، وتحصل من واجهة برمجة التطبيقات، وتعيد القيمة الحالية. قم بدمجها مع علامات العملات في الخلايا المجاورة لبناء لوحة ملخص صغيرة.

ملخص

لقد قمت بربط FXMacroData إلى كل من Excel و Google Sheets:

• استفسار طاقة Excel وظيفة M قابلة للتعديل التي تحمل أي مؤشر في جدول منظم وتحديث على الملف مفتوح.
• Excel VBA ماكرو يكتب أحدث قيمة لكل مؤشر في خلايى مسمّية، يمكن تعيينها على زر.
• برنامج Google Apps Script a refreshMacroData() وظيفة التي تبني علامة تبويب كاملة MacroData، بالإضافة إلى =FXMD() صيغة مخصصة للبحث عن كل خلية، كلاهما يتم تحديثه تلقائيًا على محرك مدفوع بالوقت.

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