واجهة برمجة تطبيقات البيانات الوصفية - دليل مطوّري البرامج

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

مقدمة

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

قبل البدء

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

  • اقرأ صفحة مكتبات العميل للحصول على قائمة كاملة بمكتبات البرامج المحددة بلغة البرمجة التي تعمل مع واجهة برمجة التطبيقات.
  • اطّلِع على الدليل المرجعي للتعرّف على واجهة واجهة برمجة التطبيقات والوصول إلى البيانات بدون مكتبة العميل.

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

  1. سجّل تطبيقك في وحدة تحكّم Google API.
  2. أنشئ كائن خدمة "إحصاءات Google" واضبط مفتاح واجهة برمجة التطبيقات.

التسجيل ومفتاح واجهة برمجة التطبيقات

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

الحصول على مفتاح واجهة برمجة تطبيقات واستخدامه

للحصول على مفتاح واجهة برمجة تطبيقات:

  1. افتح صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات.
  2. وتتوافق واجهة برمجة التطبيقات هذه مع نوعَين من بيانات الاعتماد. أنشئ بيانات الاعتماد المناسبة لمشروعك:
    • OAuth 2.0: عندما يطلب التطبيق بيانات المستخدم الخاصة، يجب أن يرسل رمز OAuth 2.0 المميز إلى جانب الطلب. يرسل تطبيقك أولاً معرِّف عميل، وربما سرًّا عميلاً للحصول على رمز مميز. يمكنك إنشاء بيانات اعتماد OAuth 2.0 لتطبيقات الويب أو حسابات الخدمة أو التطبيقات المثبّتة.

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

      لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OAuth 2.0.

    • مفاتيح واجهة برمجة التطبيقات: يجب أن يرسل الطلب الذي لا يوفّر رمز OAuth 2.0 المميز مفتاحًا لواجهة برمجة التطبيقات. يحدد المفتاح مشروعك، ويتيح الوصول إلى واجهة برمجة التطبيقات، والحصة، والتقارير.

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

للحفاظ على أمان مفاتيح واجهة برمجة التطبيقات، اتّبِع أفضل الممارسات لاستخدام مفاتيح واجهة برمجة التطبيقات بشكل آمن.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لإلحاق تطبيقك بمَعلمة طلب البحث key=yourAPIKey لجميع عناوين URL للطلب.

ويكون مفتاح واجهة برمجة التطبيقات آمنًا للتضمين في عناوين URL، ولا يحتاج إلى أي ترميز.

توضّح مقتطفات الرمز التالية كيفية ضبط مفتاح واجهة برمجة التطبيقات لمختلف مكتبات العملاء:

لغة Java

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

لغة Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

لغة PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

سمات العمود

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

إليك الجدول الكامل للسمات الصالحة:

حالات الاستخدام

يمكن استخدام واجهة برمجة تطبيقات البيانات الوصفية لحل حالات الاستخدام التالية:

الأعمدة التي تم إيقافها

إذا تم إيقاف عمود (أي سمة أو مقياس)، سيتم ضبط السمة status على DEPRECATED.

يوضّح المقتطف التالي كيفية استخدام السمة status للتحقّق مما إذا كان العمود قد تم إيقافه:

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

في حال إعادة تسمية عمود أو إزالته، سيتم ضبط سمة status على DEPRECATED وقد يتم تخصيص سمة replacedBy له في Id من العمود البديل.

يوضّح المقتطف التالي كيفية استخدام السمة replacedBy للحصول على رقم تعريف العمود البديل:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

أسماء الأعمدة

السمة uiName هي اسم المكوّن أو المقياس المستخدَم في واجهات مستخدم "إحصاءات Google" (على سبيل المثال، واجهة الويب).

يعرض المقتطف التالي كيفية استرداد اسم واجهة المستخدم للعمود:

function getColumnName(column) {
  return column.attributes.uiName;
}

الأعمدة المُقسَّمة

تشمل الأعمدة المُنسَّقة الأبعاد أو المقاييس التي تتضمن فهرسًا رقميًا. على سبيل المثال، ga:goalXXStarts وga:dimensionXX وga:metricXX وما إلى ذلك. سيحتوي العمود المُزخرَف على السمتَين minTemplateIndex وmaxTemplateIndex اللتين تحدّدان نطاق الفهرس.

يوضّح المقتطف التالي كيفية التحقق مما إذا كان العمود يتضمّن نماذج:

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

يعرض المقتطف التالي كيفية استرداد قائمة أرقام التعريف الصالحة لعمود تم نموذجه:

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

الأعمدة المحسوبة

سيحتوي العمود الناتج عن حساب أعمدة أخرى على السمة calculation. على سبيل المثال، حساب ga:percentNewSessions هو ga:newSessions / ga:sessions.

يوضّح المثال التالي كيفية التحقّق من احتساب عمود وكيفية استرداده:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

الأعمدة والشرائح

تسمح لك السمة allowedInSegments بالتحقّق مما إذا كان يمكن استخدام عمود معيّن في معلّمة طلب البحث للشريحة.

يوضّح المثال التالي كيفية تحديد ما إذا كان يمكن استخدام العمود في الشرائح:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

تمت الإضافة في إصدار واجهة برمجة التطبيقات

استخدِم السمة addedInApiVersion للتحقق من إمكانية استخدام عمود في واجهة برمجة التطبيقات لإعداد التقارير حول إصدار محدّد. على سبيل المثال، يمكنك استدعاء الدالة التالية للتحقّق من إمكانية استخدام العمود في الإصدار 3 من واجهة برمجة التطبيقات لإعداد التقارير الأساسية:

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

وضع علامة

يتم تضمين علامة ETag في كل استجابة لواجهة برمجة تطبيقات البيانات الوصفية. ETag هو معرّف يمكن استخدامه لتخزين ذاكرة التخزين المؤقت لواجهة برمجة تطبيقات البيانات الوصفية وتحديثها. تُعدّ هذه الخطوة مهمة لأنه يمكن أن تظل بيانات الأعمدة (أي السمات والمقاييس) بدون تغيير لفترات زمنية طويلة، وبالتالي لا يمكن إجراء طلبات وتعديلات غير ضرورية عند استخدام البيانات المخزّنة مؤقتًا.

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

التحقّق من ردّ مخزّن مؤقتًا

إذا قارنت قيمة ETag المعروضة من استجابة واجهة برمجة تطبيقات البيانات الوصفية والتي تساوي علامة ETag لمورد مخزَّن مؤقتًا، تكون النسخة المخزّنة مؤقتًا حالية. إذا لم تكن علامات ETAG متساوية، عليك تحديث تطبيقك وإعادة تحميل ذاكرة التخزين المؤقت بأحدث رد.

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

استخدام ETag مع طلب واجهة برمجة تطبيقات

إذا كانت لديك نسخة مخزَّنة مؤقتًا من مجموعة أعمدة، يمكنك تضمين قيمة ETag في طلب واجهة برمجة تطبيقات البيانات الوصفية من خلال ضبط الحقل عنوان HTTP If-None-Match. ستتحقّق واجهة برمجة التطبيقات للبيانات الوصفية من قيمة ETag وستستجيب بإصدار محدّث من المورد وحالة HTTP 200 OK أو استجابة فارغة بالحالة 304 Not Modified إذا كانت النسخة المخزّنة مؤقتًا.