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

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

المحتويات

نظرة عامة

مصدر البيانات هو خدمة ويب تدعم بروتوكول مصدر بيانات أدوات المخططات. ويمكنك إرسال طلب بحث بلغة الاستعلامات البنيوية (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"، احرص على استخدام الوضع IFRAME.

معالجة الردّ

سيتم استدعاء دالة معالج الاستجابة عند عرض الطلب. المعلمة التي تم تمريرها إلى دالة معالج الاستجابة هي من النوع 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 (قيم مفصولة بفواصل)، فلديك خياران. يمكنك إما تحويل بيانات CSV يدويًا إلى تنسيق جدول بيانات "مخططات Google"، أو وضع ملف CSV على خادم الويب الذي يعرض الرسم البياني، وإجراء طلب بحث عنه باستخدام الأسلوب في هذه الصفحة.

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

• بنية لغة طلب البحث: تصف بنية اللغة المستخدمة في إنشاء طلبات البيانات.
• فئة طلب البحث: هي صفحة مرجعية للفئة التي تتضمّن طلب بحث.
• فئة QueryResponse، وهي صفحة مرجعية للفئة التي تتضمّن الردّ على طلب بحث.