جداول بيانات Google

توضح هذه الصفحة كيفية استخدام مخططات Google مع جداول بيانات Google.

1. المقدمة
2. تضمين رسم بياني في جدول بيانات
3. إنشاء رسم بياني من جدول بيانات منفصل

مقدمة

يتم دمج جداول بيانات Google وجداول بيانات Google بإحكام. يمكنك وضع مخطط Google داخل جدول بيانات Google، ويمكن لمخططات Google استخراج البيانات من جداول بيانات Google. ويوضح لك هذا المستند كيفية إجراء كلا الأمرين.

بغض النظر عن الطريقة التي تختارها، سيتغير المخطط كلما تغير جدول البيانات الأساسي.

تضمين مخطط في جدول بيانات

يعد تضمين مخطط في جدول بيانات أمرًا سهلاً. من شريط أدوات جداول البيانات، حدد "إدراج" ثم "مخطط"، وستتمكن من اختيار نوع المخطط وتحديد خيارات متعددة:

إنشاء رسم بياني من جدول بيانات منفصل

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

function drawChart() {
  var query = new google.visualization.Query(URL);
  query.send(handleQueryResponse);
}

function handleQueryResponse(response) {
  var data = response.getDataTable();
  var chart = new google.visualization.ColumnChart(document.getElementById('columnchart'));
  chart.draw(data, null);
}

ويعمل هذا لأن جداول بيانات Google تدعم لغة طلب البحث في مخططات Google لتصنيف البيانات وفلترتها؛ ويمكن استخدام أي نظام يدعم لغة طلب البحث كمصدر للبيانات.

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

لاستخدام جدول بيانات Google كمصدر بيانات، ستحتاج إلى عنوان URL التالي:

1. افتح جدول بيانات حاليًا. ويجب أن يكون لجدول البيانات هذا التنسيق المتوقع في التمثيل البصري، كما يجب أن يتضمن امتيازات العرض محددة بشكل صحيح. (سيصبح عرض امتيازات "علني على الويب" أو "أي شخص لديه الرابط" أسهل طريقة، وستفترض التعليمات الواردة في هذا القسم أنّه تم إعداد جدول بيانات. يمكنك تقييد البيانات من خلال إبقاء جدول البيانات "خاص" ومنح حسابات Google الفردية إذن الوصول، ولكن عليك اتّباع تعليمات التفويض أدناه.
2. انسخ عنوان URL من المتصفّح. يمكنك الاطّلاع على نطاقات مصادر طلبات البحث للحصول على تفاصيل حول اختيار نطاقات معيّنة.
3. أرسِل عنوان URL إلى google.visualization.Query(). يتوافق طلب البحث مع المعلّمات الاختيارية التالية:
   • headers=N: تحدّد عدد الصفوف التي تكون صفوف الصفوف فيها، حيث تكون القيمة N عددًا صحيحًا صفرًا أو أكبر. سيتم استبعادها من البيانات، وسيتم تعيينها كتصنيفات للأعمدة في جدول البيانات. وإذا لم تحدِّد هذه المعلّمة، سيخمّن جدول البيانات عدد الصفوف التي تشكّل صفوف العناوين. تجدر الإشارة إلى أنه إذا كانت جميع أعمدتك عبارة عن بيانات سلسلة، قد يواجه جدول البيانات صعوبة في تحديد الصفوف التي تكون صفوف العناوين بدون هذه المعلمة.
   • gid=N: يحدّد جدول البيانات في مستند متعدد الأوراق المطلوب الربط به، إذا لم تكن مرتبطًا بالورقة الأولى. N هو رقم تعريف الورقة. يمكنك معرفة رقم التعريف عن طريق الانتقال إلى النسخة المنشورة من هذه الورقة والبحث عن معلمة gid=N في عنوان URL. يمكنك أيضًا استخدام المعلَمة sheet بدلاً من هذه المعلّمة. Gotcha: قد تُعيد جداول بيانات Google ترتيب معلّمة gid في عنوان URL عند عرضها في المتصفّح. وفي حال النسخ من متصفّح، تأكّد من أنّ كل المعلّمات قبل علامة # لعنوان URL. مثال: gid=1545912003.
   • sheet=sheet_name: يتم تحديد الورقة في مستند متعدد الأوراق التي تربط بها، إذا كنت لا تربط بالورقة الأولى. sheet_name هو الاسم المعروض للورقة. مثال: sheet=Sheet5.

في ما يلي مثال كامل:

في ما يلي طريقتان لرسم هذا الرسم البياني، إحداهما تستخدم المَعلمة gid والأخرى باستخدام المَعلمة sheet. سيؤدي إدخال أي عنوان من عناوين URL في المتصفح إلى الحصول على النتيجة/البيانات نفسها للرسم البياني.

معرّف GID

    function drawGID() {
      var queryString = encodeURIComponent('SELECT A, H, O, Q, R, U LIMIT 5 OFFSET 8');

      var query = new google.visualization.Query(
          'https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?gid=0&headers=1&tq=' + queryString);
      query.send(handleQueryResponse);
    }

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

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

جدول بيانات

    function drawSheetName() {
      var queryString = encodeURIComponent('SELECT A, H, O, Q, R, U LIMIT 5 OFFSET 8');

      var query = new google.visualization.Query(
          'https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?sheet=Sheet1&headers=1&tq=' + queryString);
      query.send(handleSampleDataQueryResponse);
    }

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

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

نطاقات مصادر طلبات البحث

يحدّد عنوان URL لمصدر طلب البحث جزء جدول البيانات المطلوب استخدامه في طلب البحث: خلية معيّنة أو نطاق خلايا أو صفوف أو أعمدة أو جدول بيانات كامل. حدد النطاق باستخدام البنية "range=<range_expr>"، على سبيل المثال:

https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?range=A1:C4
   

في ما يلي بعض الأمثلة التي توضح التركيبة:

• A1:B10 - نطاق من الخلية A1 إلى B10
• 5:7 - الصفوف 5-7
• D:F - الأعمدة D-F
• A:A70 - أول 70 خلية في العمود A
• A70:A - العمود A من الصف 70 إلى النهاية
• B5:5 - B5 إلى نهاية الصف 5
• D3:D - D3 إلى نهاية العمود D
• C:C10 - من بداية العمود C إلى C10

التفويض

يتطلب تطبيق "جداول بيانات Google" بيانات اعتماد المستخدم للوصول إلى جداول البيانات الخاصة عبر واجهة برمجة التطبيقات للتمثيل البصري في Google ("/طلبات tq").

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

في الحالات التي لا تكون فيها ميزة "المشاركة باستخدام رابط" حلاً قابلاً للتطبيق، على مطوّري البرامج تغيير رمز المرور في بيانات اعتماد OAuth 2.0 المصرَّح لها بالدخول إلى نطاق واجهة برمجة تطبيقات "جداول بيانات Google" (https://www.googleapis.com/auth/spreadsheets).

يتوفر المزيد من المعلومات عن OAuth 2.0 في استخدام OAuth 2.0 للدخول إلى Google APIs

مثال: استخدام OAuth للدخول إلى /gviz/tq

المتطلبات الأساسية: الحصول على معرِّف عميل من Google Developer Console

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

للحصول على رموز OAuth المميزة لمستخدم، يجب أولاً تسجيل مشروعك في Google Developer Console والحصول على Client ID.

1. من وحدة تحكم مطوّري البرامج، أنشئ معرِّف عميل OAuth جديدًا.
2. اختر تطبيق ويب كنوع تطبيقك.
3. اختر أي اسم، فهو مخصص لمعلوماتك فقط.
4. أضِف اسم نطاقك (وأي نطاقات اختبار) باعتباره مصادر JavaScript المعتمَدة.
5. اترك عناوين URL لإعادة التوجيه المفوَّضة فارغة.

بعد النقر على "إنشاء"، انسخ معرِّف العميل للرجوع إليه في المستقبل. سر العميل ليس ضروريًا لهذا التمرين.

حدِّث موقعك الإلكتروني للحصول على بيانات اعتماد OAuth.

توفر Google مكتبة gapi.auth التي تبسط إلى حد كبير عملية الحصول على بيانات اعتماد OAuth. يستخدم نموذج الرمز أدناه هذه المكتبة للحصول على بيانات الاعتماد (طلب تفويض إذا لزم الأمر) وتمرير بيانات الاعتماد الناتجة إلى نقطة نهاية /gviz/tq.

demo.html

<html>
<body>
  <button id="authorize-button" style="visibility: hidden">Authorize</button>
  <script src="./demo.js" type="text/javascript"></script>
  <script src="https://apis.google.com/js/auth.js?onload=init"></script>
</body>
</html>

demo.js

// NOTE: You must replace the client id on the following line.
var clientId = '549821307845-9ef2xotqflhcqbv10.apps.googleusercontent.com';
var scopes = 'https://www.googleapis.com/auth/spreadsheets';

function init() {
  gapi.auth.authorize(
      {client_id: clientId, scope: scopes, immediate: true},
      handleAuthResult);
}

function handleAuthResult(authResult) {
  var authorizeButton = document.getElementById('authorize-button');
  if (authResult && !authResult.error) {
    authorizeButton.style.visibility = 'hidden';
    makeApiCall();
  } else {
    authorizeButton.style.visibility = '';
    authorizeButton.onclick = handleAuthClick;
  }
}

function handleAuthClick(event) {
  gapi.auth.authorize(
      {client_id: clientId, scope: scopes, immediate: false},
      handleAuthResult);
  return false;
}

function makeApiCall() {
  // Note: The below spreadsheet is "Public on the web" and will work
  // with or without an OAuth token.  For a better test, replace this
  // URL with a private spreadsheet.
  var tqUrl = 'https://docs.google.com/spreadsheets' +
      '/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq' +
      '?tqx=responseHandler:handleTqResponse' +
      '&access_token=' + encodeURIComponent(gapi.auth.getToken().access_token);

  document.write('<script src="' + tqUrl +'" type="text/javascript"></script>');
}

function handleTqResponse(resp) {
  document.write(JSON.stringify(resp));
}

بعد نجاح التفويض، سيعرض gapi.auth.getToken() جميع تفاصيل الاعتماد، بما في ذلك access_token التي يمكن إلحاقها بطلبات gviz/tq.

لمزيد من المعلومات عن استخدام مكتبة gapi للمصادقة، راجع:

• المصادقة باستخدام مكتبة برامج "Google APIs" للغة JavaScript
• كيفية استخدام سياسة مشاركة الموارد متعددة المصادر (CORS) للوصول إلى واجهات برمجة تطبيقات Google

استخدام نطاق drive.file

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

يمنح النطاق drive.file (https://www.googleapis.com/auth/drive.file) إذن الوصول إلى الملفات التي يفتحها المستخدم صريحًا باستخدام منتقي ملفات Google Drive الذي تم إطلاقه من خلال واجهة برمجة التطبيقات لأداة الانتقاء.

يؤدي استخدام المنتقي إلى تغيير تدفق التطبيق. بدلاً من اللصق في عنوان URL أو استخدام جدول بيانات مشفّر كما في المثال أعلاه، يجب أن يستخدم المستخدم مربع الحوار "منتقي" لاختيار جدول البيانات الذي يريد أن تصل إليه صفحتك. اتّبِع مثال "Hello Hello" للعالِم، باستخدام google.picker.ViewId.SPREADSHEETS بدلاً من google.picker.ViewId.PHOTOS.