تنفيذ بروتوكول مصدر بيانات الرسم البياني لأدوات (الإصدار 0.6)

تصف هذه الصفحة كيفية تنفيذ خدمة تتوافق مع بروتوكول مصدر بيانات أدوات الرسم البياني لعرض البيانات في الرسوم البيانية باستخدام فئة طلب البحث.

المحتويات

  1. الجمهور
  2. نظرة عامة
  3. اعتبارات الأمان
  4. تنسيق الطلب
  5. تنسيق الرد
    1. تنسيق استجابة JSON
    2. تنسيق استجابة CSV
    3. تنسيق استجابة HTML
  6. أمثلة
  7. أدوات التطوير

الجمهور

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

تم إعداد هذه الصفحة أيضًا للقرّاء المهتمين بفهم بروتوكول الأسلاك المستخدَم للتواصل بين التمثيل البصري للعميل ومصدر البيانات.

إذا كنت تنشئ التمثيل البصري أو تستخدمه، لن تحتاج إلى قراءة هذه الصفحة.

لقراءة هذا المستند، يجب أن تفهم بنية طلب JSON وHTTP الأساسية. يجب أيضًا أن تفهم آلية عمل الرسوم البيانية من منظور المستخدم.

ملاحظة: لا تدعم Google رسميًا أي مصادر بيانات غير تابعة لـ Google وتدعم بروتوكول مصدر البيانات لأدوات الرسم البياني أو تدعمها.

نظرة عامة

يمكنك تنفيذ بروتوكول مصدر بيانات أدوات الرسم البياني لتصبح مورد مصدر بيانات للرسوم البيانية الخاصة بك أو مخططات أخرى. يعرض مصدر بيانات أدوات الرسم البياني عنوان URL، يُسمى عنوان URL لمصدر البيانات، ويمكن للرسم البياني إرسال طلبات HTTP GET إليه. واستجابةً لذلك، يعرض مصدر البيانات بيانات منسّقة بشكل صحيح يمكن للرسم البياني استخدامها لعرض الرسم على الصفحة. يُعرَف بروتوكول الاستجابة للطلب هذا باسم بروتوكول الأسلاك لواجهة برمجة تطبيقات الرسوم المرئية في Google.

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

بصفتك مصدر بيانات لأدوات الرسم البياني، يجب تحليل الطلب بتنسيق معيّن، وعرض استجابة بتنسيق محدّد. ويمكنك إجراء ذلك بإحدى طريقتين عامتين:

  • استخدم إحدى المكتبات المساعدة التالية لمعالجة الطلب والاستجابة، وأنشئ جدول البيانات لعرضه. إذا كنت تستخدم إحدى هذه المكتبات، لن تحتاج إلا إلى كتابة الرمز اللازم فقط لإتاحة بياناتك للمكتبة في شكل جدول.
    • مكتبة مصدر بيانات جافا - تعالج الطلب والاستجابة وتنشئ جدول الاستجابة من البيانات التي تقدّمها، وتنفِّذ لغة طلب بحث SQL في "رسومات بيانية لـ "أدوات Google".
    • Python Datasource Library - لإنشاء جدول استجابة ينشئ بنية الاستجابة. لا يتعامل مع تحليل الطلب أو تنفيذ لغة طلب بحث "أدوات الرسم البياني في SQL".

      أو

  • كتابة مصدر البيانات الخاص بك من البداية من خلال معالجة الطلب وإنشاء جدول بيانات وإرسال الرد

آلية العمل:

  1. يعرض مصدر البيانات عنوان URL يُعرف باسم عنوان URL لمصدر البيانات، والذي ترسل إليه الرسوم البيانية طلب HTTP GET.
  2. يُجري العميل طلب HTTP GET بمعلمات تصف التنسيق المطلوب استخدامه للبيانات المعروضة، وسلسلة طلب بحث اختيارية، ومعلمات مخصصة اختيارية.
  3. ويتلقّى مصدر البيانات الطلب ويحلّله، كما هو موضّح في تنسيق الطلب.
  4. يعمل مصدر البيانات على إعداد البيانات بالتنسيق المطلوب؛ وعادةً ما يكون هذا جدول JSON. تتم تغطية تنسيقات الردود في قسم تنسيق الاستجابة. يمكن أن يوفّر مصدر البيانات اختياريًا لغة طلب البحث في واجهة برمجة التطبيقات المرئية التي تحدّد الفلترة والترتيب والمعالجة الأخرى للبيانات.
  5. ينشئ مصدر البيانات استجابة HTTP تتضمّن البيانات المتسلسلة ومَعلمات الاستجابة الأخرى، ويعيد إرسالها إلى البرنامج كما هو موضّح في تنسيق الاستجابة.

ملاحظة: إنّ كل المعلّمات والقيم الثابتة للسلسلة الواردة في هذا المستند للطلبات والردود (مثل responseHandler و"ok") تكون أحرفًا صغيرة وحساسة لحالة الأحرف.

الحد الأدنى من المتطلبات

في ما يلي الحد الأدنى من المتطلبات لتكون مصدر بيانات أدوات الرسم البياني:

  • يجب أن يقبل مصدر البيانات طلبات HTTP GET ويجب أن يكون متاحًا لعملائك.
  • يمكن أن يتغيّر البروتوكول ويتوافق مع مخطط الإصدار (الإصدار الحالي هو 0.6)، لذلك يجب أن يتوافق مصدر البيانات مع الطلبات التي تستخدم الإصدارات السابقة بالإضافة إلى الإصدار الحالي. وعليك محاولة دعم الإصدارات الجديدة فور إصدارها لتجنّب إيقاف أي برامج تتم ترقيتها إلى أحدث إصدار بسرعة.
  • لا تفشل إذا تم إرسال خصائص غير معروفة كجزء من الطلب. ويرجع ذلك إلى أن الإصدارات الجديدة يمكنها تقديم سمات جديدة لا تكون على دراية بها.
  • تحليل الخصائص التي تتوقعها فقط: على الرغم من أنّ الإصدارات الجديدة قد تقدّم خصائص جديدة، لا تقبل بشكل متكرّر سلسلة الطلب بأكملها وتستخدمها. لحماية نفسك من الهجمات الضارة، يجب تحليل الخصائص التي تتوقعها فقط واستخدامها بعناية.
  • دوِّن متطلبات مصدر البيانات بعناية في حال عدم ترميز الرسوم البيانية للبرنامج بنفسك. ويشمل ذلك توثيق المعلومات التالية:
    • أية معلمات مخصصة تقبلها،
    • ما إذا كان بإمكانك تحليل لغة طلب بحث واجهة برمجة تطبيقات Google المرئية
    • نوع البيانات التي تعرضها وبنية هذه البيانات (ما تمثّله الصفوف والأعمدة وأي تصنيف).
  • اتخاذ جميع الاحتياطات الأمنية القياسية لأي موقع يقبل الطلبات الواردة من برامج غير معروفة. يمكنك دعم MD5 والتجزئة وغيرها من آليات الأمان الأخرى في المعلّمات من أجل المصادقة على الطلبات أو المساعدة في الحماية من الهجمات الضارة، وتوقع أن يكون العملاء على دراية بمتطلباتك والاستجابة لها. ومع ذلك، احرص على توثيق جميع المتطلبات جيدًا، في حال عدم ترميز الرسومات البيانية بنفسك. راجع اعتبارات الأمان أدناه.
  • يجب ترميز جميع سلاسل الطلبات والردود باستخدام UTF-8.
  • إنّ تنسيق الاستجابة الأكثر أهمية هو JSON. احرص على تنفيذ تنسيق JSON أولاً، لأن هذا هو التنسيق المستخدَم في معظم الرسوم البيانية. ويمكنك إضافة أنواع ردود أخرى لاحقًا.
  • لست ملزمًا بدعم لغة الاستعلام عن واجهة برمجة التطبيقات في المرئيات، ولكنها تجعل مصدر بياناتك أكثر فائدة للعملاء.
  • أنت غير مطلوب لدعم الطلبات من جميع أنواع الرسوم البيانية، ويمكنك دعم المعلّمات المخصّصة للرسوم البيانية المخصّصة. ولكن عليك عرض الردود بالتنسيق العادي الموضّح أدناه.

اعتبارات الأمان

عند تصميم مصدر بياناتك، يجب مراعاة مدى أمان بياناتك. يمكنك استخدام مجموعة متنوعة من حيل الأمان لموقعك الإلكتروني، بدءًا من الوصول البسيط إلى كلمة المرور وصولاً إلى مصادقة ملفات تعريف الارتباط الآمنة.

إن هجمات XSSI (تضمين النصوص البرمجية للمواقع المتقاطعة) تشكّل خطرًا بسبب الرسوم البيانية. قد ينتقل المستخدم إلى صفحة تحتوي على نص برمجي ضار يبدأ في محاولة إجراء طلبات بحث عن عناوين URL لمصدر البيانات، باستخدام بيانات اعتماد المستخدم الحالي. إذا لم يسجّل المستخدم الخروج من موقع إلكتروني، ستتم مصادقة النص البرمجي كمستخدم حالي وسيتمتّع بأذونات على ذلك الموقع الإلكتروني. باستخدام علامة <script src>، يمكن أن يتضمن النص البرمجي الضار مصدر البيانات، على غرار JSONP.

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

للتأكّد من أنّ الطلب صادر فعليًا من نطاقك وليس من نطاق خارجي (أو متصفّح داخل النطاق الذي يخضع لهجوم XSRF):

  • تحقق من وجود رأس "X-DataSource-Auth" في الطلب. يتم تحديد هذا العنوان من خلال واجهة برمجة تطبيقات الرسوم المرئية في Google، ولا تحتاج إلى فحص محتوى هذا الرأس، ولكن يجب التأكّد من وجوده. إذا كنت تستخدم مكتبة مصدر بيانات أدوات الرسم البياني من Google، يمكنك جعل المكتبة تتعامل مع هذا الأمر نيابةً عنك.
  • استخدِم مصادقة ملفات تعريف الارتباط لمصادقة البرنامج. ما مِن طريقة معروفة لإدخال رؤوس مخصّصة في طلب على مستوى النطاقات مع الاحتفاظ بملفات تعريف الارتباط للمصادقة في مكانها.
  • تأكد من عدم إمكانية تنفيذ JavaScript عند تضمينها مع علامة <script src>. ولإجراء ذلك، يجب إضافة بادئة الاستجابة لـ JSON بـ }]، ثم إضافة سطر جديد. في البرنامج، أزِل البادئة من الاستجابة. بالنسبة إلى XmlHttpRequest، لا يمكن إجراء ذلك إلا عندما يكون الطلب صادرًا من النطاق نفسه.

تنسيق الطلب

يرسل العميل طلب HTTP GET مع معلَمات متعددة، بما في ذلك العناصر المخصّصة وسلسلة طلب بحث اختيارية وتوقيع وعناصر أخرى. أنت مسؤول فقط عن تحليل المعلمات الموضحة في هذا القسم، ويجب أن تحرص على عدم التعامل مع المعلمات الأخرى لتجنب الهجمات الضارة.

تأكد من وجود قيم افتراضية للمعلمات الاختيارية (العادية والقياسية)، ووثّق كل القيم التلقائية في مستندات موقعك الإلكتروني.

في ما يلي بعض نماذج الطلبات (يمكنك الاطّلاع على المزيد من نماذج الطلبات والردود في نهاية هذا المستند في أمثلة):

ملاحظة: يجب تخطي عناوين URL التالية لسلاسل الطلبات وتلك المعروضة في قسم الأمثلة قبل الإرسال.

Basic request, no parameters:
http://www.example.com/mydatasource

Request with the tqx parameter that contains two properties:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Request with a query string:
http://www.example.com/mydatasource?tq=limit 1

في ما يلي قائمة بجميع المعلّمات العادية في سلسلة الطلب. يُرجى العِلم أنّ أسماء المعلّمات (مثل "الإصدار") وقيم السلسلة الثابتة (مثل "حسنًا" و"تحذير" و"not_modified") حسّاسة لحالة الأحرف. ويوضّح الجدول أيضًا ما إذا كانت المعلَمة مطلوبة للإرسال، وما إذا كان عليك معالجتها إذا تم إرسالها.

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

طلب بحث مكتوب باستخدام لغة طلب بحث واجهة برمجة تطبيقات الرسوم المرئية في Google ويحدد كيفية تصفية البيانات المعروضة أو ترتيبها أو معالجتها بطريقة أخرى. وليس من الضروري اقتباس السلسلة.

مثال: http://www.example.com/mydatasource?tq=select Col1
فريق tqx
لا
نعم

مجموعة من أزواج المفتاح/القيمة المحدّدة بنقطتين للمعلمات العادية أو المخصّصة. يتم فصل الأزواج باستخدام الفواصل المنقوطة. في ما يلي قائمة بالمعلمات العادية التي يحدّدها بروتوكول التمثيل البصري:

  • reqId - [مطلوبة عند الطلب، يجب أن يعالج مصدر البيانات] معرّف رقمي لهذا الطلب. يتم استخدام هذه الطريقة بحيث إذا أرسل عميل طلبات متعددة قبل أن يتلقّى ردًا، يمكن لمصدر البيانات التعرّف على الاستجابة من خلال الطلب المناسب. أعِد إرسال هذه القيمة في الرد.
  • version - [اختيارية في الطلب، يجب أن يتعامل مع مصدر البيانات] رقم إصدار بروتوكول Google المرئية. الإصدار الحالي هو 0.6. وإذا لم يتم إرسالها، يُرجى افتراض أحدث إصدار.
  • sig - [اختيارية في الطلب، اختيارية للتعامل مع مصدر البيانات] تجزئة من DataTable التي تم إرسالها إلى هذا العميل في أي طلبات سابقة لمصدر البيانات هذا. ويهدف هذا التحسين إلى تجنُّب إرسال بيانات متطابقة إلى عميل مرتين. راجِع تحسين طلبك أدناه للحصول على معلومات حول كيفية استخدام هذا الطلب.
  • out - [اختيارية في الطلب، يجب أن يتعامل مصدر البيانات مع] سلسلة تصف تنسيق البيانات المعروضة. ويمكن أن تكون أيًّا من القيم التالية:
    • json - [القيمة التلقائية] هي سلسلة استجابة JSON (كما هو موضّح أدناه).
    • html - جدول HTML أساسي يحتوي على صفوف وأعمدة. في حال استخدام هذه السمة، يكون الوحيد هو عرض جدول HTML مع البيانات، وهو مفيد لتصحيح الأخطاء، كما هو موضّح في القسم تنسيق الاستجابة أدناه.
    • csv - قيم مفصولة بفواصل. في حال استخدام هذه السمة، يكون العنصر الوحيد الذي تم عرضه هو سلسلة بيانات بتنسيق CSV. يمكنك طلب اسم مخصّص للملف في عناوين الاستجابة من خلال تحديد معلَمة outFileName.
    يُرجى العِلم أنّ نوع البيانات الوحيد الذي سيطلبه الرسم البياني على Google Visualization API هو في أي وقت آخر هو ملف json. راجع تنسيق الاستجابة أدناه للحصول على تفاصيل حول كل نوع.
  • responseHandler - [اختيارية في الطلب، ويجب أن يتعامل مصدر البيانات مع ما يلي] اسم سلسلة دالة معالجة JavaScript على صفحة العميل التي سيتم طلبها مع الاستجابة. وإذا لم يتم تضمينها في الطلب، تكون القيمة هي "google.visibleization.Query.setResponse". سيتم إرساله مرة أخرى كجزء من الرد، ويمكنك الاطّلاع على تنسيق الرد أدناه لمعرفة كيفية إجراء ذلك.
  • outFileName - [اختيارية في الطلب، اختيارية للتعامل مع مصدر البيانات] إذا حدّدت out:csv أو out:tsv-excel، يمكنك اختياريًا طلب اسم الملف المحدّد هنا. مثال: outFileName=results.csv.

مثال: tqx=version:0.6;reqId:1;sig:5277771;out:json؛ responseHandler:myQueryHandler
tqrt
لا
لا

محجوزة: تجاهل هذه المعلّمة. تمثل هذه الخاصية الطريقة التي تم استخدامها لإرسال طلب البحث.

تنسيق الرد

يعتمد تنسيق الاستجابة على المَعلمة out للطلب التي تحدّد نوع الاستجابة المتوقّعة. يمكنك الاطّلاع على الأقسام التالية للتعرّف على كيفية الرد على كل نوع من أنواع الطلبات:

  • JSON - لعرض استجابة JSON تتضمن البيانات في كائن JavaScript الذي يمكن تمريرها مباشرة إلى دالة إنشاء DataTable لملئها. ويُعد هذا إلى حد كبير أكثر أنواع الطلبات شيوعًا، وأهم طريقة لتطبيقه بشكل صحيح.
  • CSV - لعرض قائمة قيم مسطحة مفصولة بفواصل، ليتم التعامل معها من خلال المتصفح.
  • TSV - لعرض قائمة قيم مفصولة بعلامات جدولة، ليعالجها المتصفح.
  • HTML - لعرض جدول HTML ليتم عرضه بواسطة المتصفح.

ويمكنك استخدام مكتبة مصدر بيانات التمثيل البصري لـ Google (جافا) أو مكتبة Python للتمثيل المرئي لإنشاء تنسيقات الإخراج هذه لك.

تنسيق استجابة JSON

ويكون تنسيق الاستجابة التلقائي هو JSON إذا كان الطلب يتضمّن العنوان "X-DataSource-Auth" وعنوان JSONP في الحالات الأخرى. لاحظ أن برنامج الرسوم البيانية من Google يتيح فعليًا استخدام إصدار معدّل من JSON وJSONP، فإذا كنت تستخدم مكتبات مساعدات جافا أو Python، فسيضعون الرمز المناسب لك، وإذا كنت تحلل الردود يدويًا، فراجع تعديلات JSON أدناه.

في حال فرض طلبات النطاق نفسه، عليك التحقّق من وجود عنوان "X-DataSource-Auth" في الطلب واستخدام ملفات تعريف ارتباط التفويض.

وهذا هو تنسيق الاستجابة الوحيد الذي تحدّده طريقة واجهة برمجة التطبيقات للتمثيل البصري على Google google.visualization.Query.send() . يمكنك الاطّلاع على بعض الأمثلة عن طلبات JSON وردودها في نهاية هذه الصفحة ضمن الأمثلة. يمكنك استخدام مكتبات مساعدة جافا أو Python لإنشاء سلسلة الاستجابة هذه من أجلك.

تنسيق الاستجابة هذا عبارة عن كائن JSON مرمّز بترميز UTF-8 (وهو عبارة عن كائن يحيط به أقواس معقوفة { } تفصل بينها فاصلة) ويشمل الخصائص في الجدول أدناه (يتم تعيين البيانات إلى السمة table). ويجب لفّ كائن JSON هذا في قيمة المعلَمة responseHandler من الطلب. لذلك، إذا كانت قيمة responseHandler للطلب هي "myHandler"، يجب عرض سلسلة على النحو التالي (يتم عرض موقع واحد فقط للاختصار):

"myHandler({status:ok, ...})"

إذا لم يتضمن الطلب قيمة responseHandler، تكون القيمة التلقائية هي "google.Visualization.Query.setResponse"، لذا عليك عرض سلسلة على النحو التالي (سمة واحدة فقط يتم عرضها بغرض الإيجاز):

"google.visualization.Query.setResponse({status:ok, ...})"

في ما يلي أعضاء كائن الاستجابة المتاحين:

الخاصية
مطلوبة؟
 الوصف
إصدار
لا

رقم سلسلة يمنح رقم إصدار بروتوكول التمثيل البصري للأسلاك في Google. وإذا لم يتم تحديده، يفترض العميل أحدث إصدار.

مثال: version=0.6
مُعرّف الطلب
نعم*
 رقم سلسلة يشير إلى معرّف هذا الطلب لهذا العميل. إذا كان هذا الطلب واردًا، يجب عرض القيمة نفسها. يمكنك الاطّلاع على وصف reqId في قسم الطلب للحصول على مزيد من التفاصيل.

* إذا لم يتم تحديد هذه المعلَمة في الطلب، لن يكون عليك ضبطها في الاستجابة.
الحالة
نعم

سلسلة تصف نجاح هذه العملية أو فشلها. ويجب أن تكون واحدة من القيم التالية فقط:

  • ok - تم إرسال الطلب بنجاح. يجب تضمين الجدول في السمة table.
  • warning - تم الإجراء بنجاح، ولكن حدثت بعض المشاكل. يجب تضمين الجدول في السمة table.
  • error - حدثت مشكلة. في حال إرجاع هذه السلعة، يجب عدم إرجاع table وعليك إرجاع errors.

مثال: status:'warning'
تحذيرات
فقط إذا كان status=warning

مصفوفة من عنصر واحد أو أكثر، يصف كل منها مشكلة غير فادحة. مطلوبة إذا كانت السياسة status=warning غير مسموح بها. يحتوي كل كائن على خصائص السلسلة التالية (اعرض قيمة واحدة فقط لكل موقع):

  • reason - [مطلوبة] تمثل هذه الخاصية وصفًا مكوَّنًا من كلمة واحدة للتحذير. يحدّد البروتوكول القيم التالية، ولكن يمكنك تحديد قيمك الخاصة إذا كنت بحاجة إلى ذلك (ومع ذلك، لن يعالج البرنامج القيم المخصّصة بأي طريقة خاصة). يمكنك إضافة قيمة reason واحدة فقط:
    • data_truncated - تمت إزالة بعض الصفوف في السمة DataTable المعروضة، إما لأن المستخدم أضاف سلسلة طلب بحث اقتطعت قائمة النتائج أو أن مصدر البيانات لم يرغب في عرض نتائج كاملة لسبب من الأسباب.
    • other - تحذير عام غير محدّد.
  • message - [اختيارية] سلسلة قصيرة مُقتبَسة توضّح المشكلة، ويمكن أن تُستخدم كعنوان لمربّع تنبيه. قد يتم عرض هذا للمستخدم. HTML غير معتمد.
  • detailed_message - [اختيارية] رسالة سلسلة مفصَّلة تشرح المشكلة وأي حلول ممكنة. إنّ السمة HTML الوحيدة المتوفرة هي العنصر <a> بسمة href واحدة. يتم دعم ترميز Unicode. قد يتم عرض هذا للمستخدم.

مثال: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]
الأخطاء
مطلوبة إذا كانت القيمة status=error

مصفوفة من كائن واحد أو أكثر، يصف كل منها خطأ. مطلوبة إذا status=error، غير مسموح بها بطريقة أخرى. هذه القيمة مشابهة لقيمة warnings. يُرجى العِلم أنّ الخطأ not_modified، على الرغم من أنّه خطأ، لا يُعدّ في الواقع خطأً للعميل.

تحتوي المصفوفة على أعضاء السلسلة التاليَين (تعرض قيمة واحدة فقط لكل عضو):

  • reason - [مطلوبة] مثل السمة warnings.reason، ولكن تم تحديد القيم التالية:
    • not_modified - لم تتغير البيانات منذ آخر طلب. إذا كان هذا هو سبب الخطأ، يجب ألا تكون لديك قيمة للسمة table.
    • user_not_authenticated - إذا كان مصدر البيانات يتطلب المصادقة ولم يتم، حدِّد هذه القيمة. بعد ذلك، سيعرض العميل تنبيهًا بقيمة message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other - خطأ عام غير محدّد
  • message - [اختيارية] مثل warnings.message. ملاحظة: من الممكن أن يتمكّن مستخدم ضار من استخدام سلسلة بيانات تفصيلية كوسيلة للوصول إلى البيانات غير المصرح بها، أو حتى استخدامها للهجوم على بياناتك أو موقعك الإلكتروني. إذا كنت تخزّن البيانات التي من المفترض أن تكون آمنة أو تعالج طلبات بحث المستخدمين مباشرةً، ننصحك بعدم عرض رسالة خطأ تفصيلية يمكن أن تقدّم معلومات إلى المهاجم، بل قدِّم رسالة عامة، مثل "سلسلة طلب بحث غير صالحة".
  • detailed_message - [اختيارية] مثل warnings.detailed_message. اطّلِع على التحذير للحصول على معلومات مفصّلة للغاية عن message.

مثال: status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]
سيغ
لا

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

مثال: sig:'5982206968295329967'
جدول
لا

كائن DataTable في الترميز الحرفي JavaScript، مع بياناتك. يمكنك الاطّلاع على قسم المراجع المرتبطة للحصول على تفاصيل حول تنسيق هذا الكائن. في ما يلي مثال على جدول بيانات بسيط:

{cols:[{id:'Col1',label:'',type:'number'}],
 rows:[{c:[{v:1.0,f:'1'}]},
       {c:[{v:2.0,f:'2'}]},
       {c:[{v:3.0,f:'3'}]},
       {c:[{v:1.0,f:'1'}]}
      ]
}

يجب أن تكون السمة table موجودة فقط إذا كانت status=ok أو status=warning. إذا كنت لا تعرض بيانات، يجب عدم تضمين هذه الخاصية (أي عدم إعادة إدخال الخاصية بقيمة سلسلة فارغة).

مثال: راجِع أمثلة أدناه.

 

يجب إدخال JSON بصرامة

تعرض مكتبات المساعد من Google، وجميع طلبات البحث التي يتم إرسالها إلى Google، ملف JSON/JSONP الصارم. إذا كنت لا تحلِّل الرمز الذي عرضته بنفسك، لا يهمّك ذلك. وإذا كان الأمر كذلك، يمكنك استخدام JSON.parse() لتحويل سلسلة JSON إلى كائن JavaScript. هناك اختلاف واحد في طريقة معالجة JSON من خلال واجهة برمجة التطبيقات، وهو أنه على الرغم من أنّ تنسيق JSON لا يتيح قيم "تاريخ JavaScript" (على سبيل المثال، "Date(2008,1,28,0,31,26)" الجديد، فإن واجهة برمجة التطبيقات تتيح تمثيل JSON صالحًا للتواريخ كسلسلة بالتنسيق التالي: Date(year, month, day[,hour, minute, second[, millisecond]]) حيث يكون كل شيء بعد اليوم اختياريًا ولا تستند الشهور إلى الصفر.

 

تحسين استجابات JSON

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

  1. يرسل البرنامج طلبًا إلى مصدر البيانات.
  2. يُنشئ مصدر البيانات علامة DataTable بالإضافة إلى تجزئة الكائن DataTable، ويعرض كلاً منهما في استجابته (ويتم عرض قيمة التجزئة في المَعلمة tqx.sig). يخزِّن برنامج واجهة برمجة تطبيقات الرسوم المرئية في Google القيمة DataTable وsig في ذاكرة التخزين المؤقت.
  3. يرسل البرنامج طلبًا آخر للحصول على البيانات، بما في ذلك قيمة tqx.sig المخزّنة مؤقتًا.
  4. يمكن أن يردّ مصدر البيانات بإحدى الطريقتين التاليتين:
    • في حال تغيير البيانات عن الطلب السابق، يُعيد مصدر البيانات تجزئة القيمة الجديدة DataTable والجديدة sig.
    • في حال عدم تغيّر البيانات عن الطلب السابق، يرسل مصدر البيانات status=error، reason=not_modified، sig=old_sig_value.
  5. وفي كلتا الحالتين، تحصل الصفحة التي تستضيف الرسم البياني على استجابة ناجحة، ويمكنها استرداد السمة DataTable من خلال الاتصال على QueryResponse.getDataTable(). إذا كانت البيانات متماثلة، ستكون هي النسخة المخبأة من الجدول.

ويُرجى العِلم بأنّ هذه الطريقة لا تتوافق إلا مع طلبات JSON من الرسوم البيانية التي تم إنشاؤها في واجهة برمجة تطبيقات الرسوم البيانية في Google.

تنسيق استجابة CSV

إذا كان الطلب يحدّد out:csv، لا تتضمّن الاستجابة أي بيانات وصفية، ولكن تمثل صورة بتنسيق CSV ببساطة. عادةً ما يكون جدول CSV عبارة عن قائمة مفصولة بفواصل، حيث يكون كل صف من البيانات عبارة عن قائمة قيم مفصولة بفواصل وينتهي بحرف UNIX جديد (\n). يجب أن تحتوي قيم الخلايا على النوع نفسه لكل عمود. الصف الأول هو تصنيفات الأعمدة. في ما يلي مثال على جدول يتكون من ثلاثة صفوف وثلاثة أعمدة:

A, B, C
1.0, "yes", true
2.0, "no", false
3.0, "maybe", true

لا يتم تحديد تنسيق CSV بواسطة هذا البروتوكول، ويكون مصدر البيانات مسؤولاً عن تحديد تنسيق CSV. إنّ التنسيق الشائع هو مجموعة من القيم مفصولة بفواصل (بدون مسافات متداخلة) وسطر جديد (\n) في نهاية كل صف. عندما يتلقّى المتصفّح ردًا لسلسلة ملف CSV، قد يسأل المستخدم عن التطبيق المطلوب استخدامه لفتح السلسلة، أو قد يعرض ببساطة على الشاشة. وتوفّر المكتبات مفتوحة المصدر جافا وPython طريقة لتحويل جدول بيانات إلى سلسلة CSV.

إذا تضمّن الطلب عضوًا واحدًا (outFileName) من المعلّمة tqx ، يجب أن تحاول تضمين اسم الملف المحدّد في عناوين الاستجابة.

لا يتيح الكائن google.visualization.Query طلب استجابة ملف CSV. إذا أراد أحد العملاء طلب ملف CSV، يمكنك تضمين أداة شريط أدوات التمثيل البصري في صفحتك، أو يمكنه استخدام رمز مخصّص لإنشاء الطلب، أو يمكنك تقديم رابط يحدّد صراحةً سمة out:csv في tqx، كما هو موضّح في عنوان URL للطلب التالي:

الطلب

http://www.example.com/mydatasource?tqx=reqId:1;out:csv

الردّ

Label 1,Label2\n1,a\n2,b\n3,c\n4,d

تنسيق استجابة TSV

إذا كان الطلب يحدّد out:tsv-excel، لا تتضمّن الاستجابة أي بيانات وصفية، بل تتضمّن ببساطة تمثيلاً للبيانات مفصولة بعلامات جدولة، بترميز utf-16. إذا تضمّن الطلب عضوًا واحدًا (outFileName) من المعلّمة tqx ، يجب أن تحاول تضمين اسم الملف المحدّد في عناوين الاستجابة.

تنسيق استجابة HTML

إذا كان الطلب يحدد out:html، يجب أن تكون الاستجابة صفحة HTML التي تحدد جدول HTML بالبيانات. ويفيد هذا في تصحيح أخطاء الرمز، لأن المتصفّح يمكنه عرض النتيجة بتنسيق قابل للقراءة مباشرة. ولا يمكنك إرسال طلب بحث عن استجابة HTML باستخدام الكائن google.visualization.Query. يجب إجراء طلب بحث عن استجابة HTML باستخدام رمز مخصّص، أو عن طريق كتابة عنوان URL مشابه لذلك في المتصفّح:

الطلب

http://www.example.com/mydatasource?tqx=reqId:1;out:html

الردّ

<html><body><table border='1' cellpadding='2' cellspacing='0'><tr style='font-weight: bold; background-color: #aaa;'><td>label 1</td><td>label 2</td></tr><tr bgcolor='#f0f0f0'><td align='right'>1</td><td>a</td></tr><tr bgcolor='#ffffff'><td align='right'>2</td><td>b</td></tr><tr bgcolor='#f0f0f0'><td align='right'>3</td><td>c</td></tr><tr bgcolor='#ffffff'><td align='right'>4</td><td>d</td></tr></table></body></html>

أمثلة

إليك بعض نماذج الطلبات والردود. يُرجى العِلم بأنّه لم يتمّ تجاوز الطلبات لعنوان URL، ويتم تنفيذ ذلك عادةً من خلال المتصفّح أو الكائن google.visualization.Query.

طلب بسيط: لعرض المعلومات الأساسية التي تحتوي على ثلاثة أعمدة، وجدول من أربعة صفوف.

Request:
http://www.example.com/mydatasource

Response
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'5982206968295329967',table:{cols:[{id:'Col1',label:'',type:'number'},{id:'Col2',label:'',type:'number'},{id:'Col3',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]},{c:[{v:2.0,f:'2'},{v:3.0,f:'3'},{v:4.0,f:'4'}]},{c:[{v:3.0,f:'3'},{v:4.0,f:'4'},{v:5.0,f:'5'}]},{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]}]}});

طلب بسيط من خلال معالج استجابة: يتم عرض جدول يتكون من ثلاثة أعمدة وثلاثة صفوف مع أنواع مختلفة من البيانات.

Request:
http://www.example.com/mydatasource?tqx=responseHandler:myHandlerFunction

Response
myHandlerFunction({version:'0.6',reqId:'0',status:'ok',sig:'4641982796834063168',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]},{c:[{v:'b'},{v:2.0,f:'2'},{v:new Date(2008,2,30,0,31,26),f:'3/30/08 12:31 AM'}]},{c:[{v:'c'},{v:3.0,f:'3'},{v:new Date(2008,3,30,0,31,26),f:'4/30/08 12:31 AM'}]}]}});

طلب بحث يحتوي على سلسلة طلب بحث بسيطة: يؤدي طلب عمود واحد إلى عرض عمود واحد يحتوي على أربعة صفوف.

Request:
http://www.example.com/mydatasource?tq=select Col1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'6099996038638149313',table:{cols:[{id:'Col1',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'}]},{c:[{v:2.0,f:'2'}]},{c:[{v:3.0,f:'3'}]},{c:[{v:1.0,f:'1'}]}]}});

خطأ لم يتم تعديل البيانات: مثال على خطأ not_modified.

Request:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]});

تحذير بشأن اقتطاع البيانات: مثال على تحذير data_truncated. لاحظ أن الطلب لا يزال يعرض بيانات.

Request:
http://www.example.com/mydatasource?tq=limit 1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'warning',warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}],sig:'1928724788649668508',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]}]}});

خطأ رفض الدخول: مثال على خطأ access_denied. 

Request:
http://www.example.com/mydatasource

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'access_denied',message:'Access denied',detailed_message:'Access Denied'}]});

سلسلة طلب بحث غير صالحة: مثال على طلب يتضمّن سلسلة طلب بحث غير صالحة. لاحظ أن الرسالة التفصيلية هي رسالة عامة، وليست رسالة خطأ فعلية.

Request:
http://www.example.com/mydatasource?tq=select A

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'invalid_query',message:'Invalid query',detailed_message:'Bad query string.'}]});

أدوات تطوير

  • مكتبة مصدر بيانات جافا (من Google) - تعالج الطلب والاستجابة وتنشئ جدول الاستجابة من البيانات التي تقدّمها، وتنفّذ لغة الاستعلامات البنيوية SQL للأدوات في "مخطط Google".
  • مكتبة مصدر بيانات Python (من Google) - تنشئ جدول ردود ينشئ بنية الاستجابة. لا يتعامل مع تحليل الطلب أو تطبيق لغة الاستعلامات البنيوية (SQL) على "إحصاءات Google" الخاصة بلغة الرسم البياني من Google.
  • MC-Google_Visualization (جهة خارجية) - هذه مكتبة PHP من جانب الخادم يمكنك استخدامها لتنفيذ مصدر بيانات أدوات الرسم البياني لمحركات قاعدة بيانات MySQL وSQLite وPostgreSQL باستخدام PDO.
  • bortosky-google-مرئية (جهة خارجية) - هذه مكتبة مساعدات لإنشاء جدول بيانات واجهة برمجة التطبيقات للتمثيل البصري في Google لمستخدمي NET.
  • منشئ البث المباشر في Google (جهة خارجية) - "أداة بث فيديو Google" هي أداة على جانب الخادم يمكنها تحويل البيانات من مصادر مختلفة إلى ردود طلبات بحث صالحة على مخططات Google. يتيح "أداة بث فيديو Google" لغات متعددة (على سبيل المثال، PHP وJava و .NET) والعديد من مصادر البيانات الأولية (مثل MySql).
  • TracGViz (طرف ثالث) - TracGViz هي أداة مجانية مفتوحة المصدر تقدّم مكوّنات بحيث ستتمكن أداة Trac من استخدام أدوات الرسم البياني وتنفيذ البيانات التي تديرها Trac كمصدر بيانات "أدوات الرسم البياني من Google".
  • vis-table (جهة خارجية) - مكتبة تنفّذ مصدر بيانات لأدوات رسم بياني من Google بلغة PHP ويتألف من ثلاثة أجزاء رئيسية. تطبيق جدول البيانات نفسه ومحلّل لغة طلب البحث والمنسقون.
  • تنفيذ مصدر بيانات Google في Oracle PL/SQL (طرف ثالث) - حزمة Oracle PL/SQL تمكّن Oracle من إضافة مصادر البيانات مباشرةً إلى الخادم من قاعدة البيانات لذلك، في الأساس، يمكنك استخدام أي طلب بحث من Oracle كمصدر بيانات في أدوات الرسم البياني من Google (ستعرض الحزمة ملف JSON مع البيانات). وتتوفّر هذه الخدمة دعمًا كاملاً تقريبًا للغة طلب البحث في Google.