Как сделать POST запрос в Google Apps Script?

Что такое POST запрос и зачем он нужен?

POST-запрос – это HTTP-метод, используемый для отправки данных на сервер для создания или обновления ресурса. В отличие от GET-запросов, которые получают данные с сервера, POST-запросы передают информацию. Это критически важно для операций, изменяющих состояние сервера, таких как добавление новых записей в базу данных или отправка форм.

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

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

Выбор между POST и GET зависит от того, что вы хотите сделать:

• GET: Используется для получения данных. Параметры передаются в URL, что делает их видимыми и ограничивает объем передаваемой информации. Лучше всего подходит для безопасных и идемпотентных операций (операций, которые можно выполнить несколько раз без изменения результата).
• POST: Используется для отправки данных, особенно когда нужно создать или обновить ресурс. Данные передаются в теле запроса, что позволяет передавать большие объемы информации и сохранять их конфиденциальность. Подходит для операций, изменяющих состояние сервера.

В целом, используйте POST, когда:

• Необходимо отправить конфиденциальные данные (например, пароли).
• Требуется передать большой объем данных.
• Выполняется операция, которая изменяет состояние сервера (например, создание новой записи).

Предварительные требования: что нужно знать перед началом

Прежде чем начать работать с POST-запросами в Google Apps Script, убедитесь, что у вас есть базовое понимание следующих концепций:

1. Google Apps Script: Знание основ синтаксиса JavaScript и понимание структуры проектов Google Apps Script.
2. HTTP-методы: Понимание разницы между GET, POST, PUT, DELETE и другими HTTP-методами.
3. JSON: Знание формата JSON (JavaScript Object Notation) для представления данных.
4. API: Представление о том, что такое API и как с ними взаимодействовать.
5. UrlFetchApp: Основной сервис Google Apps Script для отправки HTTP-запросов.

Отправка простого POST запроса с использованием UrlFetchApp

Базовый синтаксис UrlFetchApp.fetch() для POST запросов

UrlFetchApp.fetch() — это основная функция для выполнения HTTP-запросов в Google Apps Script. Для POST-запросов нужно указать method в параметрах запроса:

/**
 * Отправляет POST запрос по указанному URL.
 * @param {string} url - URL для отправки запроса.
 * @param {object} options - Параметры запроса.
 * @return {HTTPResponse} - Ответ от сервера.
 */
function doPostRequest(url, options) {
  try {
    const response = UrlFetchApp.fetch(url, options);
    return response;
  } catch (e) {
    Logger.log('Error: ' + e.toString());
    return null; 
  }
}

Пример: Отправка текстовых данных на сервер

В этом примере мы отправим текстовые данные на фиктивный сервер:

function sendTextData() {
  const url = 'https://example.com/api/endpoint'; // Замените на реальный URL
  const payload = 'key1=value1&key2=value2';

  const options = {
    'method': 'post',
    'payload': payload,
    'contentType': 'application/x-www-form-urlencoded'
  };

  const response = doPostRequest(url, options);
  if (response) {
    Logger.log(response.getContentText());
  }
}

Обработка ответа от сервера

После отправки POST-запроса важно обработать ответ от сервера. Это можно сделать с помощью методов объекта HTTPResponse, возвращаемого функцией UrlFetchApp.fetch():

• getContentText(): Возвращает тело ответа как текст.
• getContent(): Возвращает тело ответа как массив байтов.
• getResponseCode(): Возвращает HTTP-код ответа (например, 200 OK, 404 Not Found).
• getHeaders(): Возвращает заголовки ответа.

Отправка данных в формате JSON

Форматирование данных в JSON для POST запроса

JSON – это распространенный формат для обмена данными между клиентом и сервером. Чтобы отправить данные в формате JSON, необходимо сначала преобразовать объект JavaScript в JSON-строку с помощью JSON.stringify():

const data = {
  'name': 'John Doe',
  'email': 'john.doe@example.com'
};

const jsonData = JSON.stringify(data);

Установка заголовка Content-Type: application/json

Для того, чтобы сервер знал, что вы отправляете JSON, необходимо установить заголовок Content-Type в значение application/json:

const options = {
  'method': 'post',
  'contentType': 'application/json',
  'payload': jsonData
};

Пример: Отправка JSON данных на API

function sendJsonData() {
  const url = 'https://example.com/api/users'; // Замените на реальный URL
  const data = {
    'name': 'Jane Doe',
    'email': 'jane.doe@example.com'
  };

  const jsonData = JSON.stringify(data);

  const options = {
    'method': 'post',
    'contentType': 'application/json',
    'payload': jsonData
  };

  const response = doPostRequest(url, options);

  if (response) {
    Logger.log(response.getContentText());
  }
}

Обработка ошибок и расширенные параметры POST запросов

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

При отправке запросов важно обрабатывать возможные ошибки. UrlFetchApp.fetch() может выбрасывать исключения, которые нужно перехватывать с помощью блока try...catch:

try {
  const response = UrlFetchApp.fetch(url, options);
  // Обработка успешного ответа
} catch (e) {
  // Обработка ошибки
  Logger.log('Error: ' + e.toString());
}

Дополнительно, можно проверять HTTP-код ответа, чтобы убедиться, что запрос был обработан успешно:

const responseCode = response.getResponseCode();
if (responseCode >= 200 && responseCode < 300) {
  // Запрос успешен
} else {
  // Запрос завершился с ошибкой
  Logger.log('Error: ' + responseCode);
}

Настройка параметров запроса: метод, заголовки, полезная нагрузка

Параметры запроса (options) позволяют настроить различные аспекты POST-запроса:

• method: HTTP-метод (в данном случае, ‘post’).
• contentType: Тип контента, отправляемого в теле запроса (например, ‘application/json’).
• payload: Данные, отправляемые на сервер. Может быть строкой или объектом.
• headers: Объект, содержащий заголовки запроса. Позволяет устанавливать собственные заголовки, такие как Authorization для аутентификации.
• muteHttpExceptions: Если установлено в true, ошибки HTTP не будут выбрасывать исключения. По умолчанию false.

Установка времени ожидания (timeout) для запроса

Чтобы предотвратить зависание скрипта в случае медленного ответа от сервера, можно установить время ожидания (timeout) в секундах:

const options = {
  'method': 'post',
  'payload': jsonData,
  'timeout': 30 // 30 секунд
};

Примеры реальных задач с использованием POST запросов в Google Apps Script

Интеграция с внешними API: отправка данных в CRM, системы аналитики и т.д.

Предположим, у вас есть CRM-система с API, которая позволяет добавлять новых клиентов. Вы можете автоматизировать процесс добавления клиентов из Google Sheets, отправляя POST-запросы к API CRM с данными клиента.

Автоматизация: создание или обновление записей в базах данных через API

Многие базы данных (например, PostgreSQL, MySQL) предоставляют API для взаимодействия. Google Apps Script может использовать POST-запросы для создания или обновления записей в этих базах данных.

Отправка данных из Google Sheets или Docs через POST запросы

Представьте, что вам нужно отправить данные из Google Sheets в стороннюю систему. Вы можете написать скрипт, который будет считывать данные из таблицы и отправлять их в виде JSON-запроса к нужному API.

Например, для интеграции с Google Analytics API (measurement protocol):

function sendAnalyticsEvent(category, action, label) {
  const trackingId = 'UA-XXXXX-Y'; // Замените на ваш tracking ID
  const clientId = Utilities.getUuid();
  const url = 'https://www.google-analytics.com/mp/collect?measurement_id=' + trackingId + '&api_secret=YOUR_API_SECRET';

  const data = {
    'client_id': clientId,
    'events': [{
      'name': 'event_name',
      'params': {
        'event_category': category,
        'event_action': action,
        'event_label': label
      }
    }]
  };

  const options = {
    'method': 'post',
    'contentType': 'application/json',
    'payload': JSON.stringify(data)
  };

  UrlFetchApp.fetch(url, options);
}