Authentication

تتيح موصلات المنتدى طرق المصادقة التالية:

• OAuth 2.0
• المسار/اسم المستخدم/كلمة المرور
• المسار/المفتاح
• اسم المستخدم/كلمة المرور
• اسم المستخدم/الرمز المميّز
• المفتاح
• بدون

استنادًا إلى الطريقة التي تستخدمها، يجب توفير وظائف إضافية في أداة الربط.

يوضّح الجدول التالي الدوال التي يجب تحديدها استنادًا إلى نوع المصادقة في الموصل.

	OAUTH2	PATH_USER_PASS PATH_KEY USER_PASS USER_TOKEN KEY	لم يتم اختيار لون
getAuthType()	مطلوب	مطلوب	مطلوب
resetAuth()	مطلوب	مطلوب
isAuthValid()	مطلوب	مطلوب
authCallback()	مطلوب
get3PAuthorizationUrls()	مطلوب
setCredentials()		مطلوب

تحذير: لضمان الحفاظ على سرية بيانات الاعتماد، يجب أن يستخدم الموصل نوع مصادقة متوافقًا، ويجب ألا يعتمد على حقول إعدادات الموصل (أي getConfig) للحصول على بيانات الاعتماد.

getAuthType()

يجب أن تعرض هذه الدالة نوع المصادقة للموصل.

OAUTH2

data-studio/auth.gs

عرض على GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.OAUTH2)
      .build();
}

PATH_USER_PASS

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
    .setAuthType(cc.AuthType.PATH_USER_PASS)
    .setHelpUrl('https://www.example.org/connector-auth-help')
    .build();
}

PATH_KEY

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
    .setAuthType(cc.AuthType.PATH_KEY)
    .setHelpUrl('https://www.example.org/connector-auth-help')
    .build();
}

USER_PASS

data-studio/auth.gs

عرض على GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.USER_PASS)
      .setHelpUrl('https://www.example.org/connector-auth-help')
      .build();
}

USER_TOKEN

data-studio/auth.gs

عرض على GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.USER_TOKEN)
      .setHelpUrl('https://www.example.org/connector-auth-help')
      .build();
}

المفتاح

data-studio/auth.gs

عرض على GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.KEY)
      .setHelpUrl('https://www.example.org/connector-auth-help')
      .build();
}

لم يتم اختيار لون

data-studio/auth.gs

عرض على GitHub

/**
 * Returns the Auth Type of this connector.
 * @return {object} The Auth type.
 */
function getAuthType() {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.NONE)
      .build();
}

ملاحظة: يمكنك الاطّلاع على getAuthType() للحصول على المستندات الكاملة.

resetAuth()

ستؤدي هذه الدالة إلى محو أي بيانات اعتماد مخزَّنة للمستخدم في الخدمة التابعة لجهة خارجية.

OAUTH2

data-studio/auth.gs

عرض على GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  getOAuthService().reset();
}

PATH_USER_PASS

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.path');
  userProperties.deleteProperty('dscc.username');
  userProperties.deleteProperty('dscc.password');
}

PATH_KEY

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.path');
  userProperties.deleteProperty('dscc.key');
}

USER_PASS

data-studio/auth.gs

عرض على GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.username');
  userProperties.deleteProperty('dscc.password');
}

USER_TOKEN

data-studio/auth.gs

عرض على GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userTokenProperties = PropertiesService.getUserProperties();
  userTokenProperties.deleteProperty('dscc.username');
  userTokenProperties.deleteProperty('dscc.password');
}

المفتاح

data-studio/auth.gs

عرض على GitHub

/**
 * Resets the auth service.
 */
function resetAuth() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('dscc.key');
}

ملاحظة: يمكنك الاطّلاع على resetAuth() للحصول على المستندات الكاملة.

isAuthValid()

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

OAUTH2

data-studio/auth.gs

عرض على GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  return getOAuthService().hasAccess();
}

PATH_USER_PASS

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var path = userProperties.getProperty('dscc.path');
  var userName = userProperties.getProperty('dscc.username');
  var password = userProperties.getProperty('dscc.password');
  // This assumes you have a validateCredentials function that
  // can validate if the path, userName and password are correct.
  return validateCredentials(path, userName, password);
}

PATH_KEY

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var path = userProperties.getProperty('dscc.path');
  var key = userProperties.getProperty('dscc.key');
  // This assumes you have a validateCredentials function that
  // can validate if the path and key are correct.
  return validateCredentials(path, key);
}

USER_PASS

data-studio/auth.gs

عرض على GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var userName = userProperties.getProperty('dscc.username');
  var password = userProperties.getProperty('dscc.password');
  // This assumes you have a validateCredentials function that
  // can validate if the userName and password are correct.
  return validateCredentials(userName, password);
}

USER_TOKEN

data-studio/auth.gs

عرض على GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var userName = userProperties.getProperty('dscc.username');
  var token = userProperties.getProperty('dscc.token');
  // This assumes you have a validateCredentials function that
  // can validate if the userName and token are correct.
  return validateCredentials(userName, token);
}

المفتاح

data-studio/auth.gs

عرض على GitHub

/**
 * Returns true if the auth service has access.
 * @return {boolean} True if the auth service has access.
 */
function isAuthValid() {
  var userProperties = PropertiesService.getUserProperties();
  var key = userProperties.getProperty('dscc.key');
  // This assumes you have a validateKey function that can validate
  // if the key is valid.
  return validateKey(key);
}

ملاحظة: يمكنك الاطّلاع على isAuthValid() للحصول على المستندات الكاملة.

OAUTH2

إضافة وإعداد OAuth2 لمكتبة Apps Script

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

على سبيل المثال، خدمة OAuth2 باسم exampleService:

data-studio/auth.gs

عرض على GitHub

/**
 * Returns the configured OAuth Service.
 * @return {Service} The OAuth Service
 */
function getOAuthService() {
  return OAuth2.createService('exampleService')
      .setAuthorizationBaseUrl('...')
      .setTokenUrl('...')
      .setClientId('...')
      .setClientSecret('...')
      .setPropertyStore(PropertiesService.getUserProperties())
      .setCallbackFunction('authCallback')
      .setScope('...');
};

authCallback()

يتم استدعاء هذه الدالة لإكمال عملية OAuth 2.0. يتم تقديم ردّ الاتصال من خدمة المصادقة التابعة لجهة خارجية كمعلَمة، ويجب أن تعالج هذه الدالة هذا الردّ.

مثال على معالجة معاودة الاتصال OAuth 2.0 باستخدام مكتبة OAuth2 لـ Apps Script:

data-studio/auth.gs

عرض على GitHub

/**
 * The OAuth callback.
 * @param {object} request The request data received from the OAuth flow.
 * @return {HtmlOutput} The HTML output to show to the user.
 */
function authCallback(request) {
  var authorized = getOAuthService().handleCallback(request);
  if (authorized) {
    return HtmlService.createHtmlOutput('Success! You can close this tab.');
  } else {
    return HtmlService.createHtmlOutput('Denied. You can close this tab');
  };
};

get3PAuthorizationUrls()

يتم استدعاء هذه الدالة للحصول على عنوان URL المطلوب لبدء عملية المصادقة الخاصة بالخدمة التابعة لجهة خارجية. إذا عرضت isAuthValid القيمة false، سيتم عرض عنوان URL الذي تم عرضه للمستخدم على شكل زر أو رابط ليتمكّن من منح الإذن بالوصول إلى خدمة الجهة الخارجية. اطّلِع على المرجع الخاص بالدالة get3PAuthorizationUrls().

مثال على عرض عنوان URL الخاص بالمصادقة باستخدام مكتبة OAuth2 لـ Apps Script:

data-studio/auth.gs

عرض على GitHub

/**
 * Gets the 3P authorization URL.
 * @return {string} The authorization URL.
 * @see https://developers.google.com/apps-script/reference/script/authorization-info
 */
function get3PAuthorizationUrls() {
  return getOAuthService().getAuthorizationUrl();
}

ملاحظة: إذا كنت تستخدم الخدمات المتقدّمة في Apps Script أو واجهات Google API للموصل، قد تحتاج إلى إثبات ملكية الموصل. لمزيد من التفاصيل، يُرجى الاطّلاع على التحقّق من عميل OAuth.

USER_PASS وUSER_TOKEN وKEY وPATH_USER_PASS وPATH_KEY

لا يلزم توفير ما يلي إلا لعمليات المصادقة USER_PASS وUSER_TOKEN وKEY وPATH_USER_PASS وPATH_KEY.

setCredentials()

يتم استدعاء setCredentials بعد أن يُدخل المستخدم معلومات بيانات الاعتماد في صفحة إعداد أداة ربط Community Connector. يجب استخدام خدمة الخصائص لحفظ بيانات الاعتماد لكل مستخدم على حدة باستخدام UserProperties.

PATH_USER_PASS

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var creds = request.pathUserPass;
  var path = creds.path;
  var username = creds.username;
  var password = creds.password;

  // Optional
  // Check if the provided path, username and password are valid through
  // a call to your service. You would have to have a `checkForValidCreds`
  // function defined for this to work.
  var validCreds = checkForValidCreds(path, username, password);
  if (!validCreds) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.path', path);
  userProperties.setProperty('dscc.username', username);
  userProperties.setProperty('dscc.password', password);
  return {
    errorCode: 'NONE'
  };
}

PATH_KEY

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var creds = request.pathKey;
  var path = creds.path;
  var key = creds.key;

  // Optional
  // Check if the provided path and key are valid through
  // a call to your service. You would have to have a `checkForValidCreds`
  // function defined for this to work.
  var validCreds = checkForValidCreds(path, key);
  if (!validCreds) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.path', path);
  userProperties.setProperty('dscc.key', key);
  return {
    errorCode: 'NONE'
  };
}

USER_PASS

data-studio/auth.gs

عرض على GitHub

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var creds = request.userPass;
  var username = creds.username;
  var password = creds.password;

  // Optional
  // Check if the provided username and password are valid through a
  // call to your service. You would have to have a `checkForValidCreds`
  // function defined for this to work.
  var validCreds = checkForValidCreds(username, password);
  if (!validCreds) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.username', username);
  userProperties.setProperty('dscc.password', password);
  return {
    errorCode: 'NONE'
  };
}

USER_TOKEN

data-studio/auth.gs

عرض على GitHub

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var creds = request.userToken;
  var username = creds.username;
  var token = creds.token;

  // Optional
  // Check if the provided username and token are valid through a
  // call to your service. You would have to have a `checkForValidCreds`
  // function defined for this to work.
  var validCreds = checkForValidCreds(username, token);
  if (!validCreds) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.username', username);
  userProperties.setProperty('dscc.token', token);
  return {
    errorCode: 'NONE'
  };
}

المفتاح

data-studio/auth.gs

عرض على GitHub

/**
 * Sets the credentials.
 * @param {Request} request The set credentials request.
 * @return {object} An object with an errorCode.
 */
function setCredentials(request) {
  var key = request.key;

  // Optional
  // Check if the provided key is valid through a call to your service.
  // You would have to have a `checkForValidKey` function defined for
  // this to work.
  var validKey = checkForValidKey(key);
  if (!validKey) {
    return {
      errorCode: 'INVALID_CREDENTIALS'
    };
  }
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty('dscc.key', key);
  return {
    errorCode: 'NONE'
  };
}

ملاحظة: يمكنك الاطّلاع على setCredentials() للحصول على المستندات الكاملة.