Определение ключа скрипта и его назначение
Ключ скрипта (script ID) в Google Apps Script — это уникальный идентификатор, присваиваемый каждому проекту Apps Script. Он служит своего рода «адресом» скрипта, позволяя другим приложениям и сервисам идентифицировать и взаимодействовать с ним.
Основное назначение ключа скрипта:
Идентификация скрипта: Позволяет однозначно определить, к какому именно скрипту обращается вызывающая сторона.
Разрешение доступа: В некоторых сценариях ключ скрипта может использоваться для управления доступом к скрипту.
Выполнение функций: С помощью ключа скрипта и определенных API можно вызывать функции, определенные в скрипте, извне.
Различия между ключом скрипта и ID проекта Apps Script
Важно понимать разницу между ключом скрипта (script ID) и ID проекта Google Cloud Platform (GCP project ID), связанного с вашим Apps Script.
Ключ скрипта уникален для каждого проекта Apps Script. Он остается неизменным на протяжении всего жизненного цикла скрипта. Он используется для идентификации скрипта в контексте Apps Script.
ID проекта GCP идентифицирует проект в Google Cloud Platform. Он используется для управления ресурсами GCP, такими как API, сервисные аккаунты и квоты. Apps Script может быть связан с проектом GCP, но это не обязательно. Если Apps Script не связан с явно указанным GCP-проектом, он использует дефолтный GCP-проект, созданный Google. Использование GCP project id необходимо, к примеру, для продвинутой аутентификации, использования сторонних библиотек требующих oauth и т.д.
В контексте работы с Apps Script, как правило, используется ключ скрипта. ID проекта GCP важен при настройке интеграций с другими сервисами Google Cloud.
Когда и зачем нужен ключ скрипта
Ключ скрипта необходим в следующих ситуациях:
Использование Script API: Для вызова функций Apps Script из других приложений через Script API.
Создание веб-приложений: Когда Apps Script выступает в роли backend’а для веб-приложения, ключ скрипта может использоваться для аутентификации запросов.
Разработка аддонов: Ключ скрипта используется при публикации аддонов в Google Workspace Marketplace.
Интеграция с внешними сервисами: В некоторых случаях, внешние сервисы могут требовать ключ скрипта для авторизации доступа к данным Google.
Как получить ключ скрипта Google Apps Script
Получение ключа скрипта из редактора Apps Script
Самый простой способ получить ключ скрипта — через редактор Apps Script:
Откройте проект Apps Script.
Выберите Настройки проекта (Project Settings) в меню слева.
Найдите поле ID скрипта (Script ID). Значение в этом поле и есть ключ скрипта.
Использование Deployment API для получения ключа
Если вам нужно автоматизировать получение ключа скрипта, можно использовать Deployment API.
/**
* @param {string} deploymentId - The deployment ID.
* @return {string} The script ID.
*/
function getScriptIdFromDeployment(deploymentId: string): string {
// This requires the Apps Script API to be enabled.
const deployment = AppsScript.Deployments.get(deploymentId);
return deployment.scriptId;
}
// Example usage:
const deploymentId = "YOUR_DEPLOYMENT_ID";
const scriptId = getScriptIdFromDeployment(deploymentId);
console.log("Script ID: " + scriptId);Где найти ключ скрипта в интерфейсе Apps Script
Как уже упоминалось, ключ скрипта находится в Настройках проекта (Project Settings) в редакторе Apps Script. Он также отображается в URL редактора Apps Script.
Использование ключа скрипта
Передача ключа скрипта в URL или параметрах запроса
При использовании Script API, ключ скрипта передается в URL запроса.
Пример:
https://script.googleapis.com/v1/scripts/{ключ_скрипта}:run
Также, ключ скрипта может передаваться как параметр запроса, в зависимости от используемого API.
Примеры использования ключа скрипта для выполнения функций
Следующий пример демонстрирует использование Script API для вызова функции Apps Script извне:
/**
* @param {string} scriptId - The script ID.
* @param {string} functionName - The function name to execute.
* @param {Array} parameters - The parameters to pass to the function.
* @return {any} The result of the function execution.
*/
function executeAppsScriptFunction(scriptId: string, functionName: string, parameters: Array): any {
const url = `https://script.googleapis.com/v1/scripts/${scriptId}:run`;
const accessToken = ScriptApp.getOAuthToken();
const payload = {
'function': functionName,
'parameters': parameters,
'devMode': true // Optional: Enable development mode
};
const options = {
'method': 'POST',
'contentType': 'application/json',
'headers': {
'Authorization': 'Bearer ' + accessToken
},
'payload': JSON.stringify(payload)
};
const response = UrlFetchApp.fetch(url, options);
const jsonResponse = JSON.parse(response.getContentText());
if (jsonResponse.error) {
throw new Error(jsonResponse.error.message);
}
return jsonResponse.response.result;
}
// Example usage:
const scriptId = "YOUR_SCRIPT_ID";
const functionName = "myFunction";
const parameters = ["param1", 123];
try {
const result = executeAppsScriptFunction(scriptId, functionName, parameters);
console.log("Result: " + result);
} catch (e) {
console.error("Error: " + e);
}Аутентификация и авторизация с использованием ключа скрипта
Как правило, ключ скрипта сам по себе не обеспечивает достаточную аутентификацию. Для безопасного доступа к Apps Script необходимо использовать OAuth 2.0. Пример выше демонстрирует использование ScriptApp.getOAuthToken() для получения токена доступа.
Безопасность ключа скрипта: лучшие практики
Ограничение доступа к скрипту с помощью ключа
Несмотря на то, что ключ скрипта не является секретным ключом, важно ограничивать доступ к скрипту. Это можно сделать, ограничив права доступа для пользователей, имеющих доступ к редактору Apps Script.
Рекомендации по защите ключа скрипта от несанкционированного доступа
Не публикуйте ключ скрипта в открытом доступе: Избегайте размещения ключа скрипта в общедоступных репозиториях кода, на форумах и т.д.
Используйте переменные окружения: Если ключ скрипта необходимо использовать в коде, храните его в переменных окружения, а не в самом коде.
Регулярно проверяйте логи: Отслеживайте логи выполнения скрипта на предмет подозрительной активности.
Управление разрешениями и scope при использовании ключа скрипта
При использовании Script API, необходимо указать соответствующие scopes в манифесте скрипта. Scopes определяют, к каким данным Google имеет доступ скрипт. Указывайте только те scopes, которые необходимы для работы скрипта.
Риски, связанные с компрометацией ключа скрипта и способы их предотвращения
Компрометация ключа скрипта может привести к несанкционированному доступу к скрипту и, возможно, к данным, которые он обрабатывает. Чтобы предотвратить это, следуйте рекомендациям, указанным выше.
Управление версиями и ключами скриптов
Обновление и ротация ключей скриптов
Ключ скрипта нельзя изменить. Однако, вы можете создать новую версию скрипта и получить новый ключ. Это полезно в случаях, когда вы подозреваете компрометацию ключа.
Управление несколькими версиями скрипта и их ключами
Каждая версия скрипта имеет свой ключ. Вы можете использовать Deployment API для управления различными версиями скрипта и их ключами.
Удаление и деактивация ключа скрипта
Ключ скрипта нельзя удалить. Однако, можно удалить deployment, связанный с ключом скрипта, что сделает невозможным вызов функций скрипта через Script API. Также, можно удалить сам проект Apps Script, но это приведет к потере всего кода и данных скрипта.