technical article

مشتريات واجهات API للأنظمة الكهروضوئية: تحديد JSON أو XML لكلتا نقطتي النهاية

17 نوفمبر 2026Updated: 17 نوفمبر 20267 min readتم التحقق من الحقائق
Cinn Song

Cinn Song

Founder & Chief Solutions Architect

مشتريات واجهات API للأنظمة الكهروضوئية: تحديد JSON أو XML لكلتا نقطتي النهاية

حدّد JSON أو XML صراحةً لكلٍّ من Solar Dataset Query V2 وPVWatts V8؛ إذ إن CSV موثّق للاستكشاف فقط. اشترط إحداثيات الموقع، ومدخلات الحساب، وإمكانية تتبّع ملف الطقس، وفحوص قبول خاصة بكل نقطة نهاية. وتعامل مع أي تصدير لنتائج الحساب بصيغة CSV بوصفه مُخرجًا يقدّمه التطبيق وتُحدَّد مواصفاته بصورة مستقلة.

الملخص

حدّد JSON أو XML صراحةً لكلٍّ من Solar Dataset Query V2 وPVWatts V8؛ إذ إن CSV موثّق للاستكشاف فقط. اشترط إحداثيات الموقع، ومدخلات الحساب، وإمكانية تتبّع ملف الطقس، وفحوص قبول خاصة بكل نقطة نهاية. وتعامل مع أي تصدير لنتائج الحساب بصيغة CSV بوصفه مُخرجًا يقدّمه التطبيق وتُحدَّد مواصفاته بصورة مستقلة.

النقاط الرئيسية

  • صيغتا JSON وXML موثّقتان لكلتا نقطتي النهاية؛ أما CSV فمدرجة فقط في Solar Dataset Query V2.
  • تتطلب كلتا نقطتي النهاية تحديد صيغة الاستجابة صراحةً، ولا توثّق أيٌّ منهما صيغة افتراضية.
  • يمكن لـPVWatts V8 استخدام معرّف file_id صالح ناتج عن الاستكشاف؛ ويجب إغفال dataset عند استخدام هذا المعرّف.
  • سجّل تفاصيل مصدر بيانات الطقس والمسافة، مع التمييز بين نصف قطر الاستكشاف بالأميال والمسافة المُعادة بالأمتار.
  • حدّد مدخلات الحساب، والإطار الزمني، والوحدات: فالطاقة الشهرية والقدرة لكل ساعة حقلان مختلفان في المخرجات.
  • تحقّق من محلّل استجابة كل نقطة نهاية، وتمرير ملف الطقس، والتحذيرات، ومعالجة المدخلات غير الصالحة قبل القبول.

تحديد JSON أو XML لاستكشاف بيانات المناخ وحسابات إنتاج الأنظمة الكهروضوئية

الملخص: حدّد JSON أو XML لكلٍّ من Solar Dataset Query V2 وPVWatts V8. توثّق كلتاهما صيغتَي الاستجابة هاتين؛ أما CSV فمدرجة للاستكشاف فقط. اشترط اختيار الصيغة صراحةً، وإحداثيات الموقع، ومدخلات الحساب، وإمكانية تتبّع ملف الطقس. تحقّق من كل نقطة نهاية بصورة مستقلة قبل قبول التكامل.

1. اختر صيغة تدعمها كلتا نقطتي النهاية

مشتريات واجهات API للأنظمة الكهروضوئية: تحديد JSON أو XML لكلتا نقطتي النهاية — البنية الوظيفية التفصيلية

عند إعداد مواصفات مشتريات تشمل استكشاف بيانات المناخ وحسابات إنتاج الأنظمة الكهروضوئية، اشترط صيغة استجابة مشتركة واحدة: JSON أو XML. تسرد Solar Dataset Query V2 الصيغ json وxml وcsv، بينما تسرد PVWatts V8 الصيغتَين json وxml. وتصف كلتاهما format بأنه مطلوب، دون قيمة افتراضية. وتضع عناوين URL لطلباتهما الصيغة المختارة بعد إصدار نقطة النهاية. Solar Dataset Query V2؛ PVWatts V8

الصياغة التعاقدية الموصى بها هي: «يجب أن يطلب التكامل صراحةً JSON لكلٍّ من الاستكشاف والحساب، أو XML لكليهما عندما يتطلب النظام المستقبِل ذلك. ويجب تحديد دعم CSV للاستكشاف بصورة مستقلة». اختر بين JSON وXML وفقًا لبرمجيات الاستقبال لدى المشتري ومتطلبات القبول لديه. ولا تثبت قوائم الصيغ الموثّقة وجود أفضلية في الأداء لأيٍّ من الخيارين.

تظل CSV خيارًا موثّقًا للاستكشاف. غير أن ورودها في Solar Dataset Query V2 لا يثبت دعم CSV في PVWatts V8. وإذا اقترح مقدّم العطاء تسليم نتائج الحساب بصيغة CSV، فاسأل عمّا إذا كان ذلك تصديرًا يُنشئه التطبيق، واشترط مواصفات تصدير مستقلة. ولا تقبل دعم صيغة الاستكشاف بوصفه تحققًا من واجهة الحساب.

2. حدّد آلية التمرير من الاستكشاف إلى الحساب

مشتريات واجهات API للأنظمة الكهروضوئية: تحديد JSON أو XML لكلتا نقطتي النهاية — عمليات النظام وصيانته بالتفصيل

تتطلب Solar Dataset Query V2 مفتاح API، وخط العرض، وخط الطول، وصيغة الاستجابة. وتُعيد معلومات عن ملفات المناخ المتاحة، بما فيها المعرّفات، والإحداثيات، والمسافة، ومصدر بيانات الطقس. وبالنسبة إلى مجموعة بيانات لا توجد لها نتيجة، تتضمن الاستجابة الموثّقة null وتحذيرًا. ويُوصى باشتراط احتفاظ التطبيق بهذه التحذيرات إلى جانب نتيجة الاستكشاف. Solar Dataset Query V2

تقبل PVWatts V8 إما خط عرض الموقع وخط طوله، أو file_id. ويجب أن يكون file_id معرّفًا صالحًا أعادته Solar Dataset Query V2. وعند تحديد هذا المعرّف، تنص الوثائق على عدم تمرير dataset. ولضمان تمرير قابل للتدقيق، يُوصى بتسجيل معرّف الاستكشاف المختار وإرساله صراحةً إلى نقطة نهاية الحساب. PVWatts V8

تحتاج إعدادات البحث أيضًا إلى معالجة صريحة. توثّق واجهة الاستكشاف radius بالأميال، بينما تكون قيمة distance المُعادة بالأمتار. وتنص على أن radius=0 يعثر على أقرب المحطات بصرف النظر عن المسافة، وأن all=1 يتطلب نصف قطر موجبًا. وعلى الرغم من أن الطلب التوضيحي يجمع بين نصف قطر صفري وall=1، ينبغي أن يتبع قبول المشتريات قاعدة المعلّمة، وأن يختبر نصف قطر موجبًا عند طلب جميع المحطات. Solar Dataset Query V2

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

3. عرّف مدخلات الحساب ومعاني المخرجات

لا تُغني صيغة تسلسل بيانات مشتركة عن مواصفات الحساب. تتطلب PVWatts V8 القدرة الاسمية، ونوع الوحدة، وفواقد النظام، ونوع المصفوفة، وزاوية الميل، وزاوية السمت، إلى جانب تحديد الموقع أو ملف المناخ ومعلّمات الوصول إلى API. ويُوصى باشتراط جدول لمدخلات المشروع يحدّد كل قيمة مُرسلة ويميّز بين الاختيارات المقصودة والقيم الافتراضية الموثّقة. PVWatts V8

حدّد أيضًا مستوى التفصيل الزمني للمخرجات. تعتمد PVWatts V8 النتائج الشهرية افتراضيًا، وتقبل timeframe=hourly. ومخرجات التيار المتردد AC والتيار المستمر DC الشهرية هي قيم طاقة بوحدتَي kWhac وkWhdc؛ أما مخرجات AC وDC لكل ساعة فهي قيم قدرة بوحدتَي Wac وWdc. وتمتد المصفوفات الشهرية من يناير إلى ديسمبر. ويُوصى بإدراج أسماء هذه الحقول ووحداتها وترتيبها في ورقة قبول الواجهة. PVWatts V8

لإتاحة تتبّع بيانات الطقس، اطلب الاحتفاظ بـstation_info، بما يشمل مصدر بيانات الطقس واسم ملف المورد الشمسي. وتشمل الاستجابة الموثّقة أيضًا المدخلات المستلَمة، والأخطاء، والتحذيرات، وإصدار الخدمة، ومعلومات مكتبة SSC. ويُوصى بتخزين استجابة الحساب ذات الصلة مع كل تقدير خضع للمراجعة، حتى يتمكن المشتري من فحص التكوين الذي جرت نمذجته ومصدره. PVWatts V8

4. اقبل التكامل من خلال فحوص خاصة بكل نقطة نهاية

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

اشترط فحوصًا مستقلة لمحلّل استجابة كل نقطة نهاية، حتى عندما تستخدم كلتاهما JSON أو XML. فالاستكشاف يصف ملفات المناخ المتاحة؛ بينما تُعيد PVWatts نتائج المحاكاة والبيانات الوصفية للحساب. ولذلك ينبغي أن تكون الصيغة المشتركة خيارًا تعاقديًا إلى جانب الربط الصريح بين الحقول. Solar Dataset Query V2؛ PVWatts V8

تصف كلتا الوثيقتين HTTP 422 للمعلّمات المفقودة أو غير الصالحة، وتوجّهان المستخدمين إلى قسم الأخطاء في الاستجابة. ويُوصى بتضمين حالة مدخلات غير صالحة في اختبارات القبول، والتحقق من أن التطبيق يُبلغ عن الخطأ بدلًا من عرضه بوصفه تقديرًا للإنتاج. وتنص كلتاهما أيضًا على حد قدره 1,000 طلب في الساعة؛ فاطلب من مقدّم العطاء توضيح كيفية التزام جدول الطلبات المقترح بهذا الحد. Solar Dataset Query V2؛ PVWatts V8

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

الأسئلة الشائعة

هل ينبغي أن يشترط العقد JSON أم XML؟

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

هل يمكن تحديد CSV لكلتا واجهتَي API؟

صيغة CSV موثّقة في Solar Dataset Query V2، لكنها غير مدرجة ضمن صيغ استجابة PVWatts V8. حدّد بصورة مستقلة أي تصدير لنتائج الحساب بصيغة CSV يُنشئه التطبيق.

هل يمكن للتكامل إغفال اختيار الصيغة؟

تحدّد كلتا الوثيقتين الصيغة بوصفها مطلوبة، ولا تدرجان قيمة افتراضية. اشترط اختيارها صراحةً في كل طلب.

كيف يمكن اختيار ملف مناخ جرى اكتشافه لاستخدامه في الحساب؟

مرّر معرّف الاستكشاف الصالح الخاص به بوصفه file_id في PVWatts V8. وتنص الوثائق على عدم تمرير dataset مع file_id.

هل يقصر radius=0 الاستكشاف على موقع المشروع؟

لا. فهو يختار أقرب المحطات بصرف النظر عن المسافة. افحص المسافة المُعادة قبل اعتماد سجل الطقس.

ماذا يحدث عندما لا يعثر الاستكشاف على بيانات لمجموعة بيانات؟

توثّق Solar Dataset Query V2 مخرجًا بقيمة null لتلك المجموعة وتحذيرًا. اشترط أن يحتفظ التطبيق بذلك ويُبلغ عنه.

هل تُعرض قيم AC لكل ساعة بوصفها طاقة؟

توثّق PVWatts V8 قيم ac لكل ساعة بوحدة Wac. أما ac_monthly الشهرية وac_annual السنوية فموثّقتان بوحدة kWhac.

ما الذي ينبغي التحقق منه في اختبارات قبول المدخلات غير الصالحة؟

تصف كلتا الوثيقتين HTTP 422 للمعلّمات غير الصالحة أو المفقودة. تحقّق من أن التطبيق يقرأ قسم الأخطاء ويُبلغ عن الفشل.

درجة الجودة:96/100

عن المؤلف

Cinn Song

Cinn Song

Founder & Chief Solutions Architect

Cinn Song founded SOLARTODO LIMITED and leads its smart-city infrastructure engineering — from solar, storage and integrated smart poles to the company's push into physical-AI city edge nodes: pole-mounted edge computing, vertical LLMs for smart cities, drone-based O&M with autonomous battery swapping, robotic maintenance, and high-speed counter-UAS interception. Since 2010, he has directed turnkey EPC + BOT delivery across 50+ countries, including telecom monopole supply for national grid operators, off-grid solar street-lighting for African municipalities, and integrated smart-pole programs for Gulf smart cities.

عرض جميع المنشورات

استشهد بهذا المقال

APA

Cinn Song. (2026). مشتريات واجهات API للأنظمة الكهروضوئية: تحديد JSON أو XML لكلتا نقطتي النهاية. SOLARTODO. Retrieved from https://solartodo.com/ar/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations

BibTeX
@article{solartodo_should_the_pv_software_integration_specify_json_or_xml_for_both_climate_data_discovery_and_production_calculations,
  title = {مشتريات واجهات API للأنظمة الكهروضوئية: تحديد JSON أو XML لكلتا نقطتي النهاية},
  author = {Cinn Song},
  journal = {SOLARTODO Knowledge Base},
  year = {2026},
  url = {https://solartodo.com/ar/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations},
  note = {Accessed: 2026-11-17}
}

Published: November 17, 2026 | Available at: https://solartodo.com/ar/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations

اشترك في نشرتنا الإخبارية

احصل على أحدث أخبار ورؤى الطاقة الشمسية مباشرة إلى صندوق بريدك.

عرض جميع المقالات