Что такое doPost в Google Apps Script: возврат данных и обработка запросов?

Что такое doPost и для чего он нужен?

doPost в Google Apps Script – это специальная функция, которая вызывается, когда скрипт получает HTTP POST запрос. По сути, это ваш обработчик входящих POST запросов. POST запросы используются для отправки данных на сервер, например, данных форм, JSON payload и т.д. doPost позволяет вам принимать эти данные, обрабатывать их и возвращать ответ.

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

ChatGPT

Google AI

Grok

Perplexity

В контексте Google Apps Script, doPost часто применяется для создания веб-приложений, API или для интеграции с внешними сервисами. Он позволяет создавать динамические веб-страницы и сервисы, способные принимать и обрабатывать данные от клиентов.

Когда использовать doPost вместо doGet?

Выбор между doPost и doGet зависит от типа операции, которую вы выполняете, и данных, которые передаете.

• doGet предназначен для получения данных с сервера. Параметры передаются в URL, что делает их видимыми и ограничивает объем передаваемых данных. doGet хорошо подходит для простых запросов на чтение.
• doPost предназначен для отправки данных на сервер. Данные передаются в теле запроса, что позволяет передавать большие объемы данных и сохранять их конфиденциальность. doPost идеально подходит для создания, обновления или удаления данных.

Основное различие: doGet должен быть идемпотентным (не должен изменять состояние сервера), в то время как doPost может изменять состояние сервера.

Необходимые условия для работы с doPost

Чтобы doPost работал, необходимо выполнить следующие условия:

1. Развертывание веб-приложения: Скрипт Google Apps Script должен быть развернут как веб-приложение (Publish -> Deploy as web app).
2. Настройка доступа: При развертывании необходимо указать, кто имеет право выполнять скрипт (например, только вы, все пользователи в вашем домене или все пользователи интернета) и от чьего имени выполняется скрипт (обычно, от имени пользователя, запустившего приложение).
3. URL веб-приложения: После развертывания вы получите URL веб-приложения, который и нужно использовать для отправки POST запросов.

Обработка запросов doPost

Получение данных из запроса (parameters, postData)

Внутри функции doPost вы можете получить данные из запроса с помощью объекта e (event object). Этот объект содержит информацию о запросе, включая параметры запроса и данные, переданные в теле запроса.

• e.parameters: Объект, содержащий параметры, переданные в URL (обычно пуст для POST запросов, но может содержать query string).
• e.postData: Объект, содержащий данные, переданные в теле запроса. Содержит поля contents, type, и length.

Разбор различных типов данных (JSON, form data)

В зависимости от типа данных, отправленных в теле запроса, вам может потребоваться их распарсить:

• JSON: Если данные отправлены в формате JSON, используйте JSON.parse(e.postData.contents).
• Form data: Если данные отправлены как form data (application/x-www-form-urlencoded), параметры будут доступны в e.parameters (хотя рекомендуется использовать e.postData.contents и парсить вручную).

Пример:

/**
 * Обрабатывает POST запрос.
 * @param {GoogleAppsScript.Events.DoPost} e Объект события POST запроса.
 * @return {GoogleAppsScript.HTML.HtmlOutput} Ответ в формате HTML.
 */
function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.HTML.HtmlOutput {
  try {
    const contentType: string | undefined = e.postData.type;
    let data: any;

    if (contentType === 'application/json') {
      data = JSON.parse(e.postData.contents);
    } else {
      // Обработка form data (application/x-www-form-urlencoded)
      // Внимание: для form data, e.parameters может быть использован,
      // но лучше парсить e.postData.contents вручную для контроля.
      data = e.parameters;
    }

    // Дальнейшая обработка данных...
    Logger.log(JSON.stringify(data));

    return HtmlService.createHtmlOutput('Данные успешно получены и обработаны.');
  } catch (error: any) {
    Logger.log('Ошибка при обработке запроса: ' + error);
    return HtmlService.createHtmlOutput('Ошибка при обработке запроса.');
  }
}

Валидация и очистка входящих данных

Крайне важно валидировать и очищать входящие данные перед их использованием. Это помогает предотвратить инъекции, XSS атаки и другие уязвимости. Проверяйте типы данных, диапазоны значений и используйте функции экранирования, если это необходимо.

Возврат данных из doPost

Формирование ответа в формате JSON

Часто, когда doPost используется для API, ответ формируется в формате JSON. Для этого используйте JSON.stringify() для преобразования данных в строку JSON и возвращайте ContentService.createTextOutput() с этой строкой.

Установка заголовков ответа (Content-Type)

Установите заголовок Content-Type в application/json, чтобы клиент знал, что ответ содержит JSON. Это можно сделать с помощью setContentType(ContentService.MimeType.JSON).

Пример:

/**
 * Формирует JSON ответ.
 * @param {any} data Данные для отправки в формате JSON.
 * @param {number} statusCode Код состояния HTTP.
 * @return {GoogleAppsScript.Content.TextOutput} JSON ответ с установленными заголовками.
 */
function createJsonResponse(data: any, statusCode: number = 200): GoogleAppsScript.Content.TextOutput {
  return ContentService
    .createTextOutput(JSON.stringify(data))
    .setMimeType(ContentService.MimeType.JSON)
    .setStatusCode(statusCode);
}

Обработка ошибок и возврат соответствующих кодов состояния

При возникновении ошибок возвращайте соответствующие коды состояния HTTP (например, 400 для Bad Request, 500 для Internal Server Error). Это помогает клиенту понять, что произошла ошибка и как ее обработать. В JSON ответе также можно включить сообщение об ошибке.

Примеры использования doPost

Реализация простого API для получения данных

Создайте doPost функцию, которая принимает идентификатор пользователя и возвращает данные пользователя из Google Sheet в формате JSON.

Пример обработки POST запроса от веб-формы

Создайте веб-форму, которая отправляет данные (имя, email, сообщение) на doPost функцию. Функция должна сохранять эти данные в Google Sheet и отправлять уведомление по email.

Аутентификация и авторизация запросов

Реализуйте простую аутентификацию на основе токена. Клиент отправляет токен в заголовке Authorization, doPost функция проверяет токен и, если он валиден, выполняет запрос.

Советы и лучшие практики

Безопасность при работе с doPost (защита от CSRF атак)

CSRF (Cross-Site Request Forgery) – это тип атаки, при которой злоумышленник заставляет пользователя выполнить нежелательные действия на веб-сайте, на котором он аутентифицирован. Для защиты от CSRF атак рекомендуется использовать токены CSRF. Сгенерируйте уникальный токен на стороне сервера и включите его в форму. При обработке POST запроса убедитесь, что токен, отправленный клиентом, соответствует токену, хранящемуся на сервере.

Логирование и отладка doPost запросов

Используйте Logger.log() для записи информации о входящих запросах, обработанных данных и возникших ошибках. Это поможет вам отладить функцию doPost и выявить проблемы. Google Cloud Logging может быть настроен для более продвинутого логирования.

Оптимизация производительности doPost функций

• Кэширование: Кэшируйте часто используемые данные, чтобы избежать повторных запросов к Google Sheets или другим сервисам.
• Асинхронные операции: Используйте LockService для предотвращения одновременного доступа к общим ресурсам.
• Оптимизация запросов к Sheets: Избегайте множественных вызовов SpreadsheetApp, используйте getValues() и setValues() для работы с большими диапазонами данных.