Authentication

מחברים של הקהילה תומכים בשיטות האימות הבאות:

• OAuth 2.0
• Path/Username/Password
• נתיב/מפתח
• שם משתמש/סיסמה
• שם משתמש/טוקן
• מפתח
• ללא

בהתאם לשיטה שבה אתם משתמשים, אתם צריכים לספק פונקציות נוספות במחבר.

בטבלה הבאה מפורטות הפונקציות שצריך להגדיר בהתאם לסוג האימות של המחבר.

	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();
}

KEY

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');
}

KEY

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);
}

KEY

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 for 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. תגובת הקריאה החוזרת משירות האימות של הצד השלישי מסופקת כארגומנט, והפונקציה הזו אמורה לטפל בה.

דוגמה לטיפול בקריאה חוזרת (callback) של 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 מופעל אחרי שהמשתמש מזין את פרטי הכניסה שלו בדף ההגדרה של מחבר הקהילה. כדאי להשתמש בProperties Service כדי לשמור את פרטי הכניסה על בסיס כל משתמש באמצעות 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'
  };
}

KEY

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().