Google Apps Script (GAS) позволяет автоматизировать и расширять функциональность сервисов Google Workspace. Одной из частых задач является получение URL текущего документа, таблицы или веб-приложения, с которым работает скрипт. Это может быть необходимо для логирования, генерации ссылок, интеграции с внешними системами или создания динамических пользовательских интерфейсов.

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Зачем получать текущий URL?

Логирование и аудит: Запись URL документа или таблицы при выполнении определенных операций.

Генерация отчетов: Включение прямых ссылок на источники данных в генерируемые отчеты.

Интеграция: Передача URL в другие системы (CRM, таск-трекеры) для связи объектов.

Динамические интерфейсы: Создание ссылок или кнопок в пользовательском интерфейсе, ведущих на текущий или связанный ресурс.

Отладка: Быстрая идентификация ресурса, в контексте которого выполняется скрипт.

Обзор методов и ограничений

Методы получения URL различаются в зависимости от контекста выполнения скрипта (привязанный к документу/таблице, автономный, веб-приложение). Существуют встроенные методы для получения URL активных документов и таблиц. Для веб-приложений используется другой подход для получения URL развертывания. Важно понимать, что возможности скрипта ограничены его правами доступа и контекстом выполнения.

Получение URL активного документа

Когда скрипт привязан к Google Документу или работает с открытым документом, можно легко получить его URL.

Использование `DocumentApp.getActiveDocument().getUrl()` для Google Docs

Метод getActiveDocument() возвращает объект текущего документа, а его метод getUrl() предоставляет прямую ссылку на этот документ.

Примеры кода и пояснения

/**
 * Получает и логирует URL активного Google Документа.
 *
 * @returns {string | null} URL активного документа или null, если документ недоступен.
 */
function logActiveDocumentUrl(): string | null {
  try {
    // Получаем активный документ
    const doc: GoogleAppsScript.Document.Document = DocumentApp.getActiveDocument();
    
    if (!doc) {
      Logger.log('Активный документ не найден.');
      return null;
    }
    
    // Получаем URL документа
    const docUrl: string = doc.getUrl();
    Logger.log(`URL текущего документа: ${docUrl}`);
    return docUrl;
  } catch (error: any) {
    Logger.log(`Ошибка при получении URL документа: ${error.message}`);
    return null;
  }
}

Этот код сначала получает объект активного документа, затем вызывает метод getUrl() для получения его URL и выводит результат в лог.

Обработка ошибок и исключений

Важно обрабатывать возможные исключения. Например, если скрипт выполняется не в контексте открытого документа (например, из редактора скриптов без открытого документа), getActiveDocument() может не вернуть ожидаемый объект или выполнение может прерваться. Использование try...catch позволяет корректно обработать такие ситуации.

Получение URL активной таблицы

Аналогично Google Docs, для Google Таблиц существует прямой метод получения URL.

Использование `SpreadsheetApp.getActiveSpreadsheet().getUrl()` для Google Sheets

Метод getActiveSpreadsheet() возвращает объект текущей таблицы, а его метод getUrl() предоставляет URL этой таблицы.

Примеры кода и пояснения

/**
 * Получает URL активной Google Таблицы и возвращает его.
 *
 * @returns {string | null} URL активной таблицы или null при ошибке.
 */
function getActiveSheetUrl(): string | null {
  try {
    // Получаем активную таблицу
    const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
    
    if (!ss) {
      console.error('Активная таблица не найдена.');
      return null;
    }
    
    // Получаем URL таблицы
    const sheetUrl: string = ss.getUrl();
    console.log(`URL текущей таблицы: ${sheetUrl}`);
    return sheetUrl;
    
  } catch (e: any) {
    console.error(`Не удалось получить URL таблицы: ${e}`);
    return null;
  }
}

Получение URL из скрипта, привязанного к таблице

Приведенный выше код идеально подходит для скриптов, привязанных к таблице (bound scripts). Он получает URL именно той таблицы, к которой привязан скрипт и которая активна в момент выполнения.

Получение URL веб-приложения

Для веб-приложений, развернутых с помощью Google Apps Script, получение "текущего" URL имеет свои особенности. Вы не можете получить URL, который пользователь видит в адресной строке браузера после возможных клиентских манипуляций. Однако вы можете получить URL развертывания (deployment URL) вашего скрипта.

Использование `ScriptApp.getService().getUrl()` для получения URL развертывания

Этот метод возвращает канонический URL для текущего развертывания веб-приложения. Этот URL остается неизменным для конкретной версии развертывания.

/**
 * Получает URL текущего развертывания веб-приложения.
 *
 * @returns {string | null} URL развертывания или null при ошибке.
 */
function getWebAppDeploymentUrl(): string | null {
  try {
    const serviceUrl: string = ScriptApp.getService().getUrl();
    Logger.log(`URL развертывания веб-приложения: ${serviceUrl}`);
    return serviceUrl;
  } catch (error: any) {
    Logger.log(`Ошибка при получении URL сервиса: ${error.message}`);
    // Эта ошибка обычно возникает, если скрипт не развернут как веб-приложение
    return null;
  }
}

/**
 * Пример функции doGet для веб-приложения, которая использует URL.
 *
 * @param {GoogleAppsScript.Events.DoGet} e - Объект события, содержащий параметры запроса.
 * @returns {GoogleAppsScript.HTML.HtmlOutput} HTML-вывод для пользователя.
 */
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.HTML.HtmlOutput {
  const deploymentUrl: string | null = getWebAppDeploymentUrl();
  let content: string = `
Мое Веб-Приложение
`;
  
  if (deploymentUrl) {
    content += `
Базовый URL этого приложения: ${deploymentUrl}
`;
  }
  
  // Пример получения параметров из URL
  const campaignId: string | undefined = e.parameter.utm_campaign;
  if (campaignId) {
    content += `
Маркетинговая кампания (utm_campaign): ${campaignId}
`;
  }
  
  return HtmlService.createHtmlOutput(content);
}

Особенности работы с веб-приложениями и их URL

ScriptApp.getService().getUrl() возвращает URL развертывания, а не URL конкретного запроса с параметрами.

URL может отличаться для разных версий развертывания (/dev для тестовой, /exec для основной).

Для получения параметров, переданных в URL (?param=value), используйте объект события e в функциях doGet(e) или doPost(e) (например, e.parameter.paramName или e.parameters).

Передача параметров в URL веб-приложения

Параметры добавляются к URL веб-приложения стандартным образом через ? и &: https://script.google.com/macros/s/DEPLOYMENT_ID/exec?userId=123&source=email

В функции doGet(e) эти параметры будут доступны как e.parameter.userId ('123') и e.parameter.source ('email').

Альтернативные методы и обходные пути

Хотя прямые методы getUrl() покрывают большинство сценариев для документов и таблиц, а ScriptApp.getService().getUrl() — для веб-приложений, существуют и другие подходы.

Получение URL через пользовательский интерфейс (UI Service)

Хотя UI Service (HtmlService) не предоставляет прямого метода для получения URL контейнера (документа/таблицы), его можно использовать для:

Отображения URL: Получить URL стандартным методом (getActiveDocument().getUrl()) и отобразить его в диалоговом окне или боковой панели.

Передачи URL на клиент: Использовать google.script.run для вызова серверной функции, получающей URL, и передачи его в JavaScript на стороне клиента.

Использование сервисов Drive API для получения URL

Если скрипт имеет доступ к Drive API (через расширенные сервисы Google), он может получить информацию о файле, включая его URL (alternateLink или webViewLink), по идентификатору файла.

/**
 * Получает URL файла на Google Диске по его ID.
 * Требует включения Drive API в расширенных сервисах.
 *
 * @param {string} fileId Идентификатор файла.
 * @returns {string | null} URL файла или null при ошибке.
 */
function getFileUrlFromDrive(fileId: string): string | null {
  try {
    // Убедитесь, что Drive API v2 или v3 включен в расширенных сервисах
    const file = Drive.Files.get(fileId, { fields: "webViewLink" }); // Используем webViewLink для URL в браузере
    if (file && file.webViewLink) {
      Logger.log(`URL файла (ID: ${fileId}): ${file.webViewLink}`);
      return file.webViewLink;
    }
    Logger.log(`Не удалось найти webViewLink для файла ID: ${fileId}`);
    return null;
  } catch (error: any) {
    Logger.log(`Ошибка при получении файла с Drive API: ${error.message}`);
    return null;
  }
}

/** Пример использования */
function testDriveApiUrl() {
  const spreadsheetId = SpreadsheetApp.getActiveSpreadsheet().getId();
  const url = getFileUrlFromDrive(spreadsheetId);
  if (url) {
    // Используем полученный URL
  }
}

Этот метод полезен, когда нужно получить URL файла, который не является активным в данный момент, но его ID известен.