Что такое UrlFetchApp и зачем он нужен?
UrlFetchApp — это встроенный сервис в Google Apps Script, позволяющий скриптам взаимодействовать с веб-сервисами через HTTP(S) протокол. Он выступает в роли моста, соединяющего ваш скрипт и внешний мир, давая возможность получать данные с веб-страниц, отправлять информацию на сторонние API и автоматизировать различные задачи, требующие взаимодействия с интернетом.
В сфере интернет-маркетинга и контекстной рекламы это открывает множество возможностей. Например, можно автоматизировать получение данных из рекламных API (Google Ads, Facebook Ads), анализировать позиции сайта в поисковой выдаче (SERP), мониторить цены конкурентов или собирать данные для построения отчетов.
Преимущества использования UrlFetchApp в Google Apps Script
Простота использования: UrlFetchApp имеет интуитивно понятный API, что упрощает написание кода для работы с веб-сервисами.
Интеграция с Google Workspace: Легко интегрируется с другими сервисами Google Workspace (Sheets, Docs, Forms и т.д.).
Автоматизация: Позволяет автоматизировать рутинные задачи, такие как сбор данных, обновление информации и отправка уведомлений.
Бесплатность: Использование UrlFetchApp не требует дополнительной платы (в рамках установленных лимитов Google Apps Script).
Основные методы UrlFetchApp
UrlFetchApp предоставляет несколько основных методов для работы с HTTP-запросами, среди которых:
fetch(url, params): Отправляет HTTP-запрос по указанному URL. Метод fetch является основным и позволяет отправлять как GET, так и POST запросы. Параметр params (необязательный) позволяет задать дополнительные опции запроса (метод, заголовки, тело запроса и т.д.).
getRequest(url, params): Создает объект запроса, который можно настроить и отправить позже. Используется реже.
Основы работы с UrlFetchApp: GET-запросы
Простейший GET-запрос: получение данных с веб-страницы
GET-запросы используются для получения данных с сервера. Вот простой пример:
/**
* Получает содержимое веб-страницы по указанному URL.
*
* @param {string} url URL веб-страницы.
* @return {string} Содержимое веб-страницы.
*/
function getWebPageContent(url: string): string {
try {
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url);
const content: string = response.getContentText();
return content;
} catch (e) {
Logger.log("Ошибка при получении данных: " + e);
return null;
}
}
// Пример использования:
const url: string = "https://www.example.com";
const pageContent: string = getWebPageContent(url);
if (pageContent) {
Logger.log(pageContent);
}Обработка ответа: получение кода статуса, заголовков и тела ответа
После отправки запроса важно обработать ответ, чтобы получить код статуса, заголовки и тело ответа:
/**
* Обрабатывает HTTP-ответ, извлекая код статуса, заголовки и тело ответа.
*
* @param {string} url URL запроса.
* @return {object} Объект с кодом статуса, заголовками и телом ответа.
*/
function processHttpResponse(url: string): object {
try {
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url);
const statusCode: number = response.getResponseCode();
const headers: object = response.getAllHeaders();
const content: string = response.getContentText();
return {
statusCode: statusCode,
headers: headers,
content: content
};
} catch (e) {
Logger.log("Ошибка при обработке ответа: " + e);
return null;
}
}
// Пример использования:
const url: string = "https://www.example.com";
const responseData: object = processHttpResponse(url);
if (responseData) {
Logger.log("Код статуса: " + responseData.statusCode);
Logger.log("Заголовки: " + JSON.stringify(responseData.headers));
Logger.log("Содержимое: " + responseData.content);
}Обработка различных типов контента (JSON, XML, HTML)
UrlFetchApp позволяет получать данные в различных форматах. Для работы с JSON удобно использовать встроенный объект JSON:
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch("https://api.example.com/data");
const json: object = JSON.parse(response.getContentText());
Logger.log(json.propertyName);Для XML можно использовать XmlService:
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch("https://api.example.com/data.xml");
const document: GoogleAppsScript.XML_Service.Document = XmlService.parse(response.getContentText());
const root: GoogleAppsScript.XML_Service.Element = document.getRootElement();
Logger.log(root.getName());Обработка ошибок при GET-запросах
Важно предусмотреть обработку ошибок при выполнении GET-запросов. Наиболее распространенные ошибки:
Сетевые ошибки: Нет подключения к интернету, недоступен сервер.
HTTP-ошибки: Сервер вернул код статуса ошибки (404, 500 и т.д.).
Ошибки парсинга: Не удалось распарсить полученные данные (например, невалидный JSON).
Используйте блоки try...catch для обработки исключений и логируйте ошибки для дальнейшего анализа.
Отправка данных с помощью UrlFetchApp: POST-запросы
Отправка данных в формате JSON
POST-запросы используются для отправки данных на сервер. Для отправки данных в формате JSON необходимо:
Преобразовать данные в строку JSON с помощью JSON.stringify().
Указать заголовок Content-Type: application/json.
Передать строку JSON в качестве тела запроса.
/**
* Отправляет POST-запрос с данными в формате JSON.
*
* @param {string} url URL для отправки запроса.
* @param {object} data Объект данных для отправки в формате JSON.
* @return {object} Ответ сервера.
*/
function postJsonData(url: string, data: object): object {
const payload: string = JSON.stringify(data);
const options: object = {
'method': 'post',
'contentType': 'application/json',
'payload': payload
};
try {
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url, options);
return JSON.parse(response.getContentText());
} catch (e) {
Logger.log("Ошибка при отправке POST-запроса: " + e);
return null;
}
}
// Пример использования:
const url: string = "https://api.example.com/endpoint";
const data: object = {
'key1': 'value1',
'key2': 'value2'
};
const response: object = postJsonData(url, data);
if (response) {
Logger.log(JSON.stringify(response));
}Отправка данных в формате x-www-form-urlencoded
Для отправки данных в формате x-www-form-urlencoded необходимо создать строку запроса, используя функцию encodeURIComponent для кодирования значений параметров. Заголовок Content-Type должен быть установлен в application/x-www-form-urlencoded. В Google Apps Script, payload в данном случае должен быть object, а не string. Это преобразует объект в строку запроса с использованием правильного кодирования.
function postFormUrlEncodedData(url: string, data: object): object {
const options: object = {
'method': 'post',
'contentType': 'application/x-www-form-urlencoded',
'payload': data
};
try {
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url, options);
return JSON.parse(response.getContentText());
} catch (e) {
Logger.log("Ошибка при отправке POST-запроса: " + e);
return null;
}
}
// Пример использования:
const url: string = "https://api.example.com/endpoint";
const data: object = {
'param1': 'value1',
'param2': 'value with spaces'
};
const response: object = postFormUrlEncodedData(url, data);
if (response) {
Logger.log(JSON.stringify(response));
}Установка заголовков запроса (Content-Type)
Заголовок Content-Type сообщает серверу, в каком формате отправлены данные. Правильная установка этого заголовка необходима для корректной обработки запроса сервером. Помимо рассмотренных выше application/json и application/x-www-form-urlencoded, могут использоваться другие значения, например, text/xml для отправки XML-данных.
Обработка ошибок при POST-запросах
При работе с POST-запросами также необходимо обрабатывать ошибки. Возможные причины ошибок:
Неправильный формат данных: Сервер не может распарсить полученные данные.
Ошибка валидации: Данные не соответствуют требованиям сервера.
Недостаточно прав доступа: У вас нет прав для выполнения операции.
Расширенные возможности UrlFetchApp
Использование параметров запроса (query parameters)
Параметры запроса (query parameters) передаются в URL после знака вопроса (?) и используются для фильтрации или сортировки данных.
const url: string = "https://api.example.com/data?param1=value1¶m2=value2";
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url);Установка пользовательских заголовков запроса
Иногда требуется установить пользовательские заголовки запроса, например, для передачи токена авторизации или указания версии API:
const options: object = {
'headers': {
'Authorization': 'Bearer YOUR_TOKEN',
'X-API-Version': '2.0'
}
};
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url, options);Настройка опций запроса (timeouts, followRedirects, muteHttpExceptions)
UrlFetchApp позволяет настраивать различные опции запроса:
timeout: Максимальное время ожидания ответа от сервера (в миллисекундах).
followRedirects: Автоматически переходить по редиректам.
muteHttpExceptions: Не генерировать исключения при HTTP-ошибках (коды статуса 4xx и 5xx).
const options: object = {
'timeout': 30000,
'followRedirects': true,
'muteHttpExceptions': true
};
const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url, options);Авторизация: базовый доступ и OAuth2
Для доступа к API, требующим авторизации, можно использовать различные методы:
Базовый доступ: Передача имени пользователя и пароля в заголовке Authorization.
OAuth2: Использование токенов доступа, полученных через протокол OAuth2. Для работы с OAuth2 в Google Apps Script обычно используют библиотеку OAuth2.
Примеры использования UrlFetchApp в реальных задачах
Получение данных о погоде с внешнего API
Многие сервисы предоставляют API для получения данных о погоде. Например, можно использовать API OpenWeatherMap.
Интеграция с сервисами геолокации
Можно использовать API геолокации для определения координат по IP-адресу или адресу.
Автоматизация задач в Google Sheets с использованием внешних API
UrlFetchApp позволяет автоматизировать обновление данных в Google Sheets с использованием внешних API. Например, можно получать данные о курсах валют или остатках на складе и автоматически обновлять таблицу в Google Sheets.