إنشاء رابط في المنتدى

خطوات إنشاء "أداة ربط المنتدى":

1. أنشِئ مشروعًا جديدًا لبرمجة التطبيقات.
2. اكتب رمز الموصِّل.
3. أكمل بيان المشروع.

إنشاء مشروع جديد لبرمجة التطبيقات

انتقِل إلى برمجة تطبيقات Google لإنشاء مشروع جديد. ستنشئ لغة "برمجة تطبيقات Google" نصًا برمجيًا تلقائيًا لك. يمكنك إزالة دالة myFunction وإعادة تسمية المشروع. (مزيد من المعلومات عن "برمجة التطبيقات")

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

كتابة رمز الموصِّل

يلزم أن يكون لكل موصل مجموعة محددة من الدوال المحددة. سينفِّذ التطبيق المضيف (مثل Looker Studio) هذه الدوال. يُتوقّع أن يعالج الموصِّل الطلبات الواردة وأن يردّ على النحو الموضّح في مرجع واجهة برمجة تطبيقات Community Connector. إذا واجهت مشاكل أثناء تطوير التعليمات البرمجية، فاقرأ دليل تصحيح الأخطاء للحصول على المساعدة.

تحديد نوع المصادقة في getAuthType()

يتم استدعاء هذه الدالة لتحديد طريقة المصادقة المستخدمة في خدمة الجهة الخارجية. يمكنك الاطّلاع على مرجع getAuthType() للحصول على التفاصيل. طرق المصادقة المتاحة حاليًا مُدرجة في مرجع AuthType.

على سبيل المثال، لا يتطلب الموصل التالي المصادقة:

npm-downloads/src/auth.js

العرض على GitHub

var cc = DataStudioApp.createCommunityConnector();

// https://developers.google.com/datastudio/connector/reference#getauthtype
function getAuthType() {
  var AuthTypes = cc.AuthType;
  return cc
    .newAuthTypeResponse()
    .setAuthType(AuthTypes.NONE)
    .build();
}

إذا كان مصدر بياناتك يتطلب مصادقة OAuth 2.0، يمكنك عرض دليل مصادقة OAuth 2.0 وإضافة الوظائف الإضافية المطلوبة إلى الموصل.

تحديد الإعداد من خلال getConfig()

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

استنادًا إلى الرد المقدَّم من getConfig()، ستعرض أداة Looker Studio شاشة ضبط الموصل. عناصر الضبط المتوافقة مُدرَجة في مرجع ConfigType

إذا كان مصدر البيانات يتطلب التاريخ كمَعلمة، يجب استدعاء config.setDateRangeRequired(true). إذا كنت بحاجة إلى طرح أسئلة عن الضبط الشرطي أو الديناميكي، يمكنك الاطّلاع على الضبط المتدرّج.

فيما يلي مثال على موصل يتطلب من المستخدم إدخال رمز اسم حزمة npm. يتم تحديد معلومات وحقل إدخال في دالة getConfig():

npm-downloads/src/main.js

العرض على GitHub

// https://developers.google.com/datastudio/connector/reference#getconfig
function getConfig() {
  var config = cc.getConfig();

  config
    .newInfo()
    .setId('instructions')
    .setText(
      'Enter npm package names to fetch their download count. An invalid or blank entry will revert to the default value.'
    );

  config
    .newTextInput()
    .setId('package')
    .setName(
      'Enter a single package name or multiple names separated by commas (no spaces!)'
    )
    .setHelpText('e.g. "googleapis" or "package,somepackage,anotherpackage"')
    .setPlaceholder(DEFAULT_PACKAGE)
    .setAllowOverride(true);

  config.setDateRangeRequired(true);

  return config.build();
}

ملاحظة: تسهِّل خدمة "برمجة تطبيقات DataStudio" كتابة موصل منتدى. فهو يلخص الأنماط الشائعة ويوفر الإكمال التلقائي بحيث لا يلزم حفظ الطرق وقيم التعداد. للاطّلاع على المستندات المرجعية، اطّلِع على خدمة Looker Studio

.

تحديد الحقول باستخدام getSchema()

يتم استدعاء هذه الدالة للحصول على المخطط للطلب المحدد. سيتم توفير أي معلَمات ضبط تحدّدها الدالة getConfig() في الوسيطة request. يمكنك الاطّلاع على مرجع getSchema() لمعرفة مزيد من التفاصيل.

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

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

ملاحظة: بالنسبة إلى SELECT_MULTIPLE، تكون القيمة configParams عبارة عن سلسلة مفصولة بفواصل. بالنسبة إلى CHECKBOX، تكون قيمة configParam هي truthy.

npm-downloads/src/main.js

العرض على GitHub

function getFields() {
  var fields = cc.getFields();
  var types = cc.FieldType;
  var aggregations = cc.AggregationType;

  fields
    .newDimension()
    .setId('packageName')
    .setName('Package')
    .setType(types.TEXT);

  fields
    .newDimension()
    .setId('day')
    .setName('Date')
    .setType(types.YEAR_MONTH_DAY);

  fields
    .newMetric()
    .setId('downloads')
    .setName('Downloads')
    .setType(types.NUMBER)
    .setAggregation(aggregations.SUM);

  return fields;
}

// https://developers.google.com/datastudio/connector/reference#getschema
function getSchema(request) {
  return {schema: getFields().build()};
}

استرجاع البيانات وعرضها باستخدام getData()

يتم استدعاء هذه الدالة للحصول على بيانات للطلب المحدد. سيتم توفير أي معلمات ضبط تحدّدها الدالة getConfig() في الوسيطة request. يمكنك الاطّلاع على مرجع getData() لمعرفة مزيد من التفاصيل.

تتطلّب المَعلمات التالية من طلب getData() انتباهًا إضافيًا:

• lastRefresh
  تمثّل السمة lastRefresh طابعًا زمنيًا يحدّد وقت أحدث طلب لإعادة تحميل البيانات. من المفترض أن تتمكّن من تحليل القيمة باستخدام new Date(timestampString). إذا كنت تستخدم خدمة ذاكرة التخزين المؤقت لبرمجة التطبيقات أو أي طريقة أخرى للتخزين المؤقت، يمكن أن يساعدك الطابع الزمني lastRefresh في تحديد ما إذا كنت تريد إرسال طلب جلب جديد إلى مصدر البيانات أو عرض البيانات من ذاكرة التخزين المؤقت.

• dateRange
  في حال ضبط dateRangeRequired على true في getConfig()، ستحتوي كل مكالمة getData() على النطاق الزمني المحدّد في الطلب. راجِع استخدام النطاقات الزمنية للحصول على مزيد من التفاصيل.

يجلب المثال التالي البيانات بناءً على الطلب الوارد ويعرض إحصائيات الحزمة:

npm-downloads/src/main.js

العرض على GitHub

// https://developers.google.com/datastudio/connector/reference#getdata
function getData(request) {
  request.configParams = validateConfig(request.configParams);

  var requestedFields = getFields().forIds(
    request.fields.map(function(field) {
      return field.name;
    })
  );

  try {
    var apiResponse = fetchDataFromApi(request);
    var normalizedResponse = normalizeResponse(request, apiResponse);
    var data = getFormattedData(normalizedResponse, requestedFields);
  } catch (e) {
    cc.newUserError()
      .setDebugText('Error fetching data from API. Exception details: ' + e)
      .setText(
        'The connector has encountered an unrecoverable error. Please try again later, or file an issue if this error persists.'
      )
      .throwException();
  }

  return {
    schema: requestedFields.build(),
    rows: data
  };
}

/**
 * Gets response for UrlFetchApp.
 *
 * @param {Object} request Data request parameters.
 * @returns {string} Response text for UrlFetchApp.
 */
function fetchDataFromApi(request) {
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ].join('');
  var response = UrlFetchApp.fetch(url);
  return response;
}

/**
 * Parses response string into an object. Also standardizes the object structure
 * for single vs multiple packages.
 *
 * @param {Object} request Data request parameters.
 * @param {string} responseString Response from the API.
 * @return {Object} Contains package names as keys and associated download count
 *     information(object) as values.
 */
function normalizeResponse(request, responseString) {
  var response = JSON.parse(responseString);
  var package_list = request.configParams.package.split(',');
  var mapped_response = {};

  if (package_list.length == 1) {
    mapped_response[package_list[0]] = response;
  } else {
    mapped_response = response;
  }

  return mapped_response;
}

/**
 * Formats the parsed response from external data source into correct tabular
 * format and returns only the requestedFields
 *
 * @param {Object} parsedResponse The response string from external data source
 *     parsed into an object in a standard format.
 * @param {Array} requestedFields The fields requested in the getData request.
 * @returns {Array} Array containing rows of data in key-value pairs for each
 *     field.
 */
function getFormattedData(response, requestedFields) {
  var data = [];
  Object.keys(response).map(function(packageName) {
    var package = response[packageName];
    var downloadData = package.downloads;
    var formattedData = downloadData.map(function(dailyDownload) {
      return formatData(requestedFields, packageName, dailyDownload);
    });
    data = data.concat(formattedData);
  });
  return data;
}

إكمال بيان المشروع

يحتوي ملف البيان على معلومات عن "موصِّل المنتدى" المطلوبة لنشر الموصِّل واستخدامه في Looker Studio.

تنبيه: يجب اعتبار أي معلومات تضعها في ملف البيان عامة حيث يمكن لأي شخص يستخدم الموصِّل.

لتعديل ملف البيان في بيئة تطوير برمجة التطبيقات، انقر على القائمة عرض وانقر على إظهار ملف البيان. سيؤدي ذلك إلى إنشاء ملف بيان appsscript.json جديد.

يمكنك تعديل ملف البيان ليتضمن البيانات التالية:

npm-downloads/src/appsscript.json

العرض على GitHub

{
  "dependencies": {
    "libraries": []
  },
  "dataStudio": {
    "name": "npm Downloads",
    "logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20square/n-64.png",
    "company": "Google Data Studio Developer Relations",
    "companyUrl": "https://developers.google.com/datastudio/",
    "addonUrl": "https://github.com/googledatastudio/community-connectors/tree/master/npm-downloads#readme",
    "supportUrl": "https://github.com/googledatastudio/community-connectors/issues",
    "description": "Get npm package download counts.",
    "sources": ["npm"],
    "templates": {
      "default": "1twu0sHjqR5dELAPyGJcw4GS3-D0_NTrQ"
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

للحصول على تفاصيل عن بيان Looker Studio، يُرجى الاطّلاع على مرجع البيان.

الخطوات التالية

تكون الخطوة التالية هي تفعيل "موصِّل المنتدى".