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

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

مقدمة

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

قبل البدء

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

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

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

  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 التي تتضمن مجموعة فرعية من السمات التي تنطبق على العمود.

يتضمن الجدول التالي قائمة كاملة بالسمات الصالحة:

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

يمكن استخدام Metadata API لحل حالات الاستخدام التالية:

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

إذا تم إيقاف عمود (أي سمة أو مقياس) نهائيًا، سيتم ضبط السمة 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 في كل استجابة من Metadata API. علامة ETag هي معرّف يمكن استخدامه لتخزين ردود بيانات Metadata API مؤقتًا وتعديلها. وهذه الخطوة مهمة لأنّ بيانات الأعمدة (أي الأبعاد والمقاييس) يمكن أن تظل بدون تغيير لفترات زمنية طويلة، وليس من الضروري إجراء طلبات وتعديلات غير ضرورية عند استخدام البيانات المخزّنة مؤقتًا.

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

التحقُّق من استجابة مُخزَّنة مؤقتًا

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

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

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

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