جدولة جلب البيانات اليومي للذهب وسعر الصرف

جدولة الجلب عبر API

استخدم مفتاح Narwhal API نفسه لطلب الذهب وطلب سعر الصرف. يرسل البرنامج النصي كل طلب إلى https://api.narwhalapi.com مع الترويسة Authorization: Bearer YOUR_KEY، ثم يضيف القيم المعادة إلى daily.csv. ويحتفظ الملف بوقت الجلب إلى جانب سعر الذهب بالدولار الأمريكي وسعر USD/IDR.

1. وضع المفتاح في ملف بيئة احصل على مفتاح مجاني وضع export NARWHAL_API_KEY=... في ~/.narwhal.env. اضبط وضع الملف على 600 ليتمكن وحدك من قراءته؛ فالأمر المجدول يحمّل هذا الملف قبل تشغيل Python.
2. حفظ البرنامج النصي للجلب اليومي احفظه باسم /home/me/daily_pull.py. يكتب أسماء الأعمدة عندما يكون daily.csv جديدًا، ثم يضيف صفًا يحوي run_at_utc وxau_usd وusd_idr بعد نجاح الطلبين.
   Python، إضافة الذهب وUSD/IDR إلى ملف CSV

   #!/usr/bin/env python3
   """Append today's gold price and USD/IDR rate to daily.csv. Run it once a day."""
   
   import csv, os, pathlib
   from datetime import datetime, timezone
   import requests
   
   API = "https://api.narwhalapi.com/v1"
   H = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   gold = requests.get(f"{API}/commodities/spot/XAU/USD", headers=H, timeout=10)
   fx = requests.get(
       f"{API}/fx/rates/USD", params={"currencies": "IDR"}, headers=H, timeout=10
   )
   gold.raise_for_status()
   # a failed run exits non-zero, so cron mail or your monitor sees it
   fx.raise_for_status()
   
   path = pathlib.Path("daily.csv")
   new = not path.exists()
   with path.open("a", newline="") as f:
       w = csv.writer(f)
       if new:
           w.writerow(["run_at_utc", "xau_usd", "usd_idr"])
       w.writerow(
           [
               datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
               gold.json()["price"],
               fx.json()["rates"][0]["rate"],
           ]
       )

3. إضافة إدخال cron اليومي استخدم إدخال crontab هذا على خادم بتوقيت UTC لجدولة الجلب بعد منتصف الليل بتوقيت UTC. يقرأ المفتاح من ملف البيئة ويرسل ناتج البرنامج النصي وأخطاءه إلى /home/me/daily_pull.log.
   إدخال cron اليومي على خادم UTC

   15 1 * * * . $HOME/.narwhal.env && /usr/bin/python3 /home/me/daily_pull.py >> /home/me/daily_pull.log 2>&1

مهلة كل طلب 10 ثوانٍ. يقرأ البرنامج النصي الذهب من الحقل price في الاستجابة، وUSD/IDR من الحقل rate داخل rates، ثم يكتب القيمتين في الصف نفسه. ويضيف إلى الملف في عمليات الجلب اللاحقة، ولا يكتب ترويسة الأعمدة إلا عندما يكون الملف جديدًا.

يحتوي crontab على مسار ملف البيئة، بينما يبقى المفتاح في NARWHAL_API_KEY. تستخدم Narwhal حسابًا واحدًا ومفتاح API واحدًا ورصيدًا واحدًا عبر واجهات API للبيانات، لذا تخصم طلبات الذهب وسعر الصرف المجدولة من ذلك الرصيد. تحمل الاستجابات X-RateLimit-Remaining للحصة المتبقية من حد معدل الطلبات.

يسجّل عمود run_at_utc وقت كتابة النص البرمجي للصف. اقرأه على أنه وقت السحب. تحمل القيم اليومية ختمًا زمنيًا 00:00 UTC، لذا فإن جدولة إضافة الملف بعد منتصف الليل بتوقيت UTC تُبقي المهمة اليومية على الأساس الزمني نفسه للبيانات.

جدولة تدفق بلا برمجة

يمكن أن يبدأ التدفق اليومي بـ n8n Schedule Trigger أو Make «Schedule» أو Zapier «Schedule by Zapier». استخدم إضافة صف في Google Sheets لحفظ النتيجة. وهذا يمنح الجلب اليومي وجهة في جدول بيانات إذا أردت القيم فيه بدلًا من ملف CSV الخاص بالبرنامج النصي.

يبدأ المشغّل المجدول التدفق كل يوم؛ وتخزّن إضافة الصف نتيجة ذلك السحب. أبقِ التوقيت متوافقًا مع UTC، لأن القيم اليومية تحمل ختمًا زمنيًا 00:00 UTC. ويتبع التدفق المجدول التوقيت اليومي نفسه للنص البرمجي، مع معالجة الجدولة والتخزين داخل التدفق.

بالنسبة إلى برنامج نصي مجدول، تشمل خيارات الجدولة الأخرى Task Scheduler في Windows وlaunchd في macOS ومجدولًا سحابيًا. تبقى المهمة اليومية طلب الذهب وطلب USD/IDR. استخدم المجدول الذي يناسب المكان الذي سيعمل فيه البرنامج النصي، أو استخدم تدفقًا مجدولًا إذا لم يكن لديك خادم.

متى تستخدم كل خيار

ما المنطقة الزمنية التي يعمل بها cron؟

يستخدم cron المنطقة الزمنية للخادم. استخدم date لمعرفة وقت الخادم، واستخدم UTC لمطابقة البيانات. يفترض إدخال crontab أن الخادم بتوقيت UTC، ويعتمد توقيت ما بعد منتصف الليل على تلك المنطقة الزمنية.

تحمل أسعار الصرف اليومية ختمًا زمنيًا 00:00 UTC. ويصف هذا الختم الزمني وعمود run_at_utc في النص البرمجي وقتين مختلفين: فالسعر اليومي له ختم بيانات، بينما يسجّل ملف CSV وقت السحب. أسعار السلع والصرف مباشرة، لذا يحمل كل صف السعر لحظة تشغيل النص البرمجي.

ماذا لو فشل التشغيل اليومي؟

يخرج البرنامج النصي برمز غير صفري عند فشل أي طلب ولا يُضاف شيء. يجب أن ينجح الطلبان معًا قبل أن يفتح daily.csv لإضافة الصف. وبالتالي يترك الطلب الفاشل الملف دون صف من ذلك التشغيل.

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

في أخطاء حدود الطلبات، ميّز بين 429 rate_limit_exceeded الذي يتضمن Retry-After، و402 insufficient_credits الذي ينتظر حتى تضيف رصيدًا. استخدم التخزين المؤقت ومعالجة 429 لهذا الجزء من الجلب المجدول. وتستخدم استجابات الأخطاء application/problem+json مع status وcode وdetail وrequest_id.

مثال حسابي: شهر من عمليات الجلب اليومية

احسب طلب الذهب وطلب USD/IDR لكل عملية جلب يومية، ثم اضرب في عدد أيام الشهر. بمعدل طلبين في اليوم على مدى 31 يومًا يجري البرنامج النصي 62 استدعاءً، بتكلفة نحو $0.12 بسعر $2 لكل 1,000 استدعاء.

في 24 أكتوبر 2026، يظهر في الصف الذي وقت جلبه 2026-10-24T12:17:15Z الذهب عند 3996.00 USD وUSD/IDR عند 18107.8. في ملف CSV يأتي وقت الجلب أولًا، ثم سعر الذهب وسعر الصرف بالترتيب الذي تحدده الترويسة.

run_at_utc,xau_usd,usd_idr
2026-10-24T12:17:15Z,3996.00,18107.8