تصف هذه الصفحة كيفية تنفيذ خدمة تتوافق مع بروتوكول مصدر بيانات أدوات الرسم البياني لعرض البيانات في الرسوم البيانية باستخدام فئة طلب البحث.
المحتويات
الجمهور
هذه الصفحة مُعدّة بشكل أساسي لمطوّري البرامج الذين سينشئون مصدر بيانات خاص بهم بدون مساعدة من مكتبة مصدر البيانات في "الرسم البياني". إذا كنت تستخدم المكتبات المساعدة أو أي مكتبة أخرى، يُرجى قراءة مستندات مكتبتك أولاً.
تم إعداد هذه الصفحة أيضًا للقرّاء المهتمين بفهم بروتوكول الأسلاك المستخدَم للتواصل بين التمثيل البصري للعميل ومصدر البيانات.
إذا كنت تنشئ التمثيل البصري أو تستخدمه، لن تحتاج إلى قراءة هذه الصفحة.
لقراءة هذا المستند، يجب أن تفهم بنية طلب JSON وHTTP الأساسية. يجب أيضًا أن تفهم آلية عمل الرسوم البيانية من منظور المستخدم.
نظرة عامة
يمكنك تنفيذ بروتوكول مصدر بيانات أدوات الرسم البياني لتصبح مورد مصدر بيانات للرسوم البيانية الخاصة بك أو مخططات أخرى. يعرض مصدر بيانات أدوات الرسم البياني عنوان URL، يُسمى عنوان URL لمصدر البيانات، ويمكن للرسم البياني إرسال طلبات HTTP GET إليه. واستجابةً لذلك، يعرض مصدر البيانات بيانات منسّقة بشكل صحيح يمكن للرسم البياني استخدامها لعرض الرسم على الصفحة. يُعرَف بروتوكول الاستجابة للطلب هذا باسم بروتوكول الأسلاك لواجهة برمجة تطبيقات الرسوم المرئية في Google.
يمكن استخراج البيانات التي يعرضها مصدر بيانات من موارد متنوعة، مثل ملف أو قاعدة بيانات. القيد الوحيد هو أنه يمكنك تنسيق البيانات على شكل جدول ثنائي الأبعاد بأعمدة مكتوبة.
بصفتك مصدر بيانات لأدوات الرسم البياني، يجب تحليل الطلب بتنسيق معيّن، وعرض استجابة بتنسيق محدّد. ويمكنك إجراء ذلك بإحدى طريقتين عامتين:
-
استخدم إحدى المكتبات المساعدة التالية لمعالجة الطلب والاستجابة،
وأنشئ جدول البيانات لعرضه. إذا كنت تستخدم إحدى هذه المكتبات، لن تحتاج إلا إلى كتابة الرمز اللازم فقط لإتاحة بياناتك للمكتبة في شكل جدول.
- مكتبة مصدر بيانات جافا - تعالج الطلب والاستجابة وتنشئ جدول الاستجابة من البيانات التي تقدّمها، وتنفِّذ لغة طلب بحث SQL في "رسومات بيانية لـ "أدوات Google".
-
Python Datasource Library -
لإنشاء جدول استجابة ينشئ بنية الاستجابة. لا يتعامل مع تحليل الطلب أو تنفيذ لغة طلب بحث "أدوات الرسم البياني في SQL".
أو
- كتابة مصدر البيانات الخاص بك من البداية من خلال معالجة الطلب وإنشاء جدول بيانات وإرسال الرد
آلية العمل:
- يعرض مصدر البيانات عنوان URL يُعرف باسم عنوان URL لمصدر البيانات، والذي ترسل إليه الرسوم البيانية طلب HTTP GET.
- يُجري العميل طلب HTTP GET بمعلمات تصف التنسيق المطلوب استخدامه للبيانات المعروضة، وسلسلة طلب بحث اختيارية، ومعلمات مخصصة اختيارية.
- ويتلقّى مصدر البيانات الطلب ويحلّله، كما هو موضّح في تنسيق الطلب.
- يعمل مصدر البيانات على إعداد البيانات بالتنسيق المطلوب؛ وعادةً ما يكون هذا جدول JSON. تتم تغطية تنسيقات الردود في قسم تنسيق الاستجابة. يمكن أن يوفّر مصدر البيانات اختياريًا لغة طلب البحث في واجهة برمجة التطبيقات المرئية التي تحدّد الفلترة والترتيب والمعالجة الأخرى للبيانات.
- ينشئ مصدر البيانات استجابة 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 ويحدد كيفية تصفية البيانات المعروضة أو ترتيبها أو معالجتها بطريقة أخرى. وليس من الضروري اقتباس السلسلة. مثال: |
فريق tqx | لا |
نعم |
مجموعة من أزواج المفتاح/القيمة المحدّدة بنقطتين للمعلمات العادية أو المخصّصة. يتم فصل الأزواج باستخدام الفواصل المنقوطة. في ما يلي قائمة بالمعلمات العادية التي يحدّدها بروتوكول التمثيل البصري:
مثال: |
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. وإذا لم يتم تحديده، يفترض العميل أحدث إصدار. مثال: |
مُعرّف الطلب | نعم* |
رقم سلسلة يشير إلى معرّف هذا الطلب لهذا العميل. إذا كان
هذا الطلب واردًا، يجب عرض القيمة نفسها. يمكنك الاطّلاع على
وصف reqId في قسم الطلب للحصول على
مزيد من التفاصيل. * إذا لم يتم تحديد هذه المعلَمة في الطلب، لن يكون عليك ضبطها في الاستجابة. |
الحالة | نعم |
سلسلة تصف نجاح هذه العملية أو فشلها. ويجب أن تكون واحدة من القيم التالية فقط:
مثال: |
تحذيرات | فقط إذا كان status=warning |
مصفوفة من عنصر واحد أو أكثر، يصف كل منها مشكلة غير فادحة.
مطلوبة إذا كانت السياسة
مثال: |
الأخطاء | مطلوبة إذا كانت القيمة status=error |
مصفوفة من كائن واحد أو أكثر، يصف كل منها خطأ. مطلوبة إذا
تحتوي المصفوفة على أعضاء السلسلة التاليَين (تعرض قيمة واحدة فقط لكل عضو):
مثال:
|
سيغ | لا |
قيمة مجزأة لكائن الجدول. ويُفيد في تحسين نقل البيانات بين العميل ومصدر البيانات. يمكنك اختيار أي خوارزمية تجزئة تريدها. إذا كنت تسمح بهذه السمة، عليك إرجاع القيمة التي مرّرها العميل في حال عدم عرض أي بيانات، أو عرض تجزئة جديدة في حال عرض بيانات جديدة. مثال: |
جدول | لا |
كائن {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'}]} ] } يجب أن تكون السمة مثال: راجِع أمثلة أدناه. |
تعرض مكتبات المساعد من 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
إذا قدّم العميل طلبين، ولم تتغير البيانات بين الطلبات، من المنطقي عدم إعادة إرسال البيانات، لأن ذلك قد يؤدي إلى إهدار النطاق الترددي. لزيادة فعالية الطلبات، يتيح البروتوكول تخزين البيانات في ذاكرة التخزين المؤقت في البرنامج مؤقتًا، وإرسال إشارة في الاستجابة في حال عدم تغيّر البيانات منذ آخر طلب. وإليك كيفية العمل:
- يرسل البرنامج طلبًا إلى مصدر البيانات.
- يُنشئ مصدر البيانات علامة
DataTable
بالإضافة إلى تجزئة الكائنDataTable
، ويعرض كلاً منهما في استجابته (ويتم عرض قيمة التجزئة في المَعلمةtqx.
sig
). يخزِّن برنامج واجهة برمجة تطبيقات الرسوم المرئية في Google القيمةDataTable
وsig
في ذاكرة التخزين المؤقت. - يرسل البرنامج طلبًا آخر للحصول على البيانات، بما في ذلك قيمة
tqx.sig
المخزّنة مؤقتًا. - يمكن أن يردّ مصدر البيانات بإحدى الطريقتين التاليتين:
- في حال تغيير البيانات عن الطلب السابق، يُعيد مصدر البيانات
تجزئة القيمة الجديدة
DataTable
والجديدةsig
. - في حال عدم تغيّر البيانات عن الطلب السابق، يرسل مصدر البيانات
status=error
،reason=not_modified
،sig=old_sig_value
.
- في حال تغيير البيانات عن الطلب السابق، يُعيد مصدر البيانات
تجزئة القيمة الجديدة
- وفي كلتا الحالتين، تحصل الصفحة التي تستضيف الرسم البياني على استجابة ناجحة، ويمكنها استرداد السمة
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.