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

في ما يلي خطوات إنشاء موصِّل المنتدى:

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

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

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

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

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

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

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

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

npm-downloads/src/auth.js
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
// 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();
}
.

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

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

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

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

npm-downloads/src/main.js
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
// 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.

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

يُرجى تعديل البيان لتضمين البيانات التالية:

npm-downloads/src/appsscript.json
{
  "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، يُرجى الاطّلاع على مرجع بيان المرجع.

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

ستكون الخطوة التالية هي نشر "موصِّل المنتدى".