استعلامات البيانات

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

نظرة عامة

مصدر البيانات هو خدمة ويب تدعم بروتوكول مصدر بيانات أدوات المخططات. يمكنك إرسال استعلام SQL (لغة الاستعلام البنيوية) إلى مصدر بيانات، وفي المقابل، ستتلقى جدول بيانات مملوءًا بالمعلومات المناسبة. من الأمثلة على مصادر البيانات جداول بيانات Google وSalesforce.

إرسال طلب

لإرسال طلب:

  1. أنشئ كائن استعلام باستخدام عنوان URL لمصدر البيانات. ويجب أن يشير عنوان URL إلى البيانات المطلوبة ببنية يفهمها مصدر البيانات هذا.
  2. يمكنك تحديد خيارات الطلب، مثل طريقة الإرسال كمَعلمة ثانية اختيارية في الدالة الإنشائية للكائن Query (يمكنك الاطّلاع على المَعلمة opt_options في أداة إنشاء طلب البحث لمعرفة التفاصيل):
  3. يمكنك إضافة سلسلة لغة طلب البحث لترتيب النتائج أو فلترتها، ثم إرسال الطلب. مصادر البيانات غير مطلوبة لإتاحة لغة استعلام مصدر بيانات أدوات الرسوم البيانية. إذا كان مصدر البيانات لا يتيح استخدام لغة الاستعلام، سيتجاهل سلسلة طلب بحث SQL، ولكنه سيعرض DataTable. لغة الاستعلام هي نسخة مختلفة من لغة SQL، ويمكنك الاطّلاع على بنية لغة طلب البحث الكاملة هنا.
  4. أرسِل الطلب مع تحديد معالج معاودة الاتصال الذي سيتم طلبه عند تلقّي الردّ: راجِع القسم التالي للحصول على التفاصيل.

في ما يلي مثال على إرسال طلب للحصول على بيانات في نطاق خلايا في "جدول بيانات Google". للتعرّف على كيفية الحصول على عنوان URL لجدول بيانات Google، يُرجى الانتقال إلى هذا الرابط:

function initialize() {
  var opts = {sendMethod: 'auto'};
  // Replace the data source URL on next line with your data source URL.
  var query = new google.visualization.Query('http://spreadsheets.google.com?key=123AB&...', opts);

  // Optional request to return only column C and the sum of column B, grouped by C members.
  query.setQuery('select C, sum(B) group by C');

  // Send the query with a callback function.
  query.send(handleQueryResponse);
}

function handleQueryResponse(response) {
  // Called when the query response is returned.
  ...
}

معالجة الردّ

سيتم استدعاء دالة معالج الاستجابة عند عرض الطلب. المعلمة التي تم تمريرها إلى دالة معالج الاستجابة هي من النوع google.visualization.QueryResponse. إذا تم الطلب بنجاح، ستحتوي الاستجابة على جدول بيانات (الفئة google.visualization.DataTable). في حال تعذُّر الطلب، تتضمّن الاستجابة معلومات حول الخطأ، وليست تتضمّن DataTable.

يجب أن ينفّذ معالج الاستجابة الإجراءات التالية:

  1. تحقَّق مما إذا كان الطلب قد نجح أو لم ينجح من خلال الاتصال بالرقم response.isError(). من المفترض ألا تحتاج إلى عرض أي رسائل خطأ للمستخدم لأنّ مكتبة العروض المرئية ستعرِض رسالة خطأ لك في حاويتك <div>. مع ذلك، إذا أردت معالجة الأخطاء يدويًا، يمكنك استخدام الفئة goog.visualization.errors لعرض رسائل مخصّصة (يمكنك الاطّلاع على مثال على التفاف طلب البحث للحصول على مثال على طريقة المعالجة المخصّصة للأخطاء).
  2. إذا نجح الطلب، سيتضمّن الرد DataTable يمكنك استرداده من خلال الاتصال بـ getDataTable(). مرره إلى المخطط.

يوضح التعليمة البرمجية التالية التعامل مع الطلب السابق لرسم مخطط دائري:

function handleQueryResponse(response) {

  if (response.isError()) {
    alert('Error in query: ' + response.getMessage() + ' ' + response.getDetailedMessage());
    return;
  }

  var data = response.getDataTable();
  var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
  chart.draw(data, {width: 400, height: 240, is3D: true});
}

قراءة ملفات CSV

إذا كنت تريد إنشاء مخطط باستخدام بيانات CSV (قيم مفصولة بفواصل)، فلديك خياران:

  • تحويل البيانات إلى تنسيق جدول بيانات "مخططات Google"
  • ضع ملف CSV على خادم الويب الذي يعرض الرسم البياني، واطلب منه البحث باستخدام الأسلوب المتوفّر في هذه الصفحة.

المزيد من المعلومات