Сторонние API

Мощной функцией скриптов Google Ads является возможность интеграции с данными и сервисами сторонних API.

В этом руководстве рассматриваются следующие концепции, которые помогут вам писать скрипты для подключения к другим службам:

  • Выполнение HTTP-запросов : как использовать UrlFetchApp для доступа к внешним API.
  • Аутентификация : мы рассмотрим некоторые распространенные сценарии аутентификации.
  • Анализ ответов : как обрабатывать возвращенные данные JSON и XML.

Мы также включаем примеры для ряда популярных API, иллюстрирующие эти концепции.

Извлечение данных с помощью UrlFetchApp

UrlFetchApp предоставляет основные функции, необходимые для взаимодействия со сторонними API.

В следующем примере показано получение данных о погоде из OpenWeatherMap . Мы выбрали OpenWeatherMap из-за его относительно простой схемы авторизации и API.

Сделать запрос

В документации OpenWeatherMap указан следующий формат запроса текущей погоды :

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

URL-адрес представляет собой наш первый пример авторизации: параметр apikey обязателен, а его значение уникально для каждого пользователя. Этот ключ можно получить при регистрации .

После регистрации запрос с использованием ключа можно оформить следующим образом:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

Выполнение этого кода приводит к записи длинной строки текста JSON в окно регистрации в скриптах Google Ads.

Следующий шаг — конвертация в формат, который можно использовать в вашем сценарии.

JSON-данные

Многие API предоставляют ответы в формате JSON. Это простая сериализация объектов JavaScript, позволяющая представлять и передавать объекты, массивы и базовые типы в виде строк.

Чтобы преобразовать строку JSON, например, возвращаемую OpenWeatherMap, обратно в объект JavaScript, используйте встроенный метод JSON.parse . Продолжая пример выше:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

Метод JSON.parse преобразует строку в объект, имеющий свойство name .

Более подробную информацию о работе с ответами API в различных форматах см. в разделе Анализ ответов.

Обработка ошибок

Обработка ошибок является важным фактором при работе со сторонними API в ваших скриптах, поскольку сторонние API часто меняются и генерируют неожиданные значения ответов, например:

  • URL-адрес или параметры API могут измениться без вашего ведома.
  • Срок действия вашего ключа API (или других учетных данных пользователя) может истечь.
  • Формат ответа может быть изменен без предварительного уведомления.

HTTP-коды статуса

Из-за вероятности непредвиденных ответов следует проверять код состояния HTTP . По умолчанию UrlFetchApp генерирует исключение при обнаружении кода ошибки HTTP. Чтобы изменить это поведение, необходимо передать необязательный параметр, как в следующем примере:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

Структура ответа

При изменении сторонних API разработчики часто не сразу осознают, какие изменения могут повлиять на их скрипты. Например, если свойство name возвращаемое в примере OpenWeatherMap, изменить на locationName , скрипты, использующие это свойство, завершится ошибкой.

По этой причине может быть полезно проверить, соответствует ли возвращаемая структура ожидаемой, например:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

Данные POST с UrlFetchApp

Вводная версия OpenWeatherMap использует только извлекаемые данные. Обычно вызовы API, не изменяющие состояние на удалённом сервере, используют HTTP GET .

Метод GET используется по умолчанию для UrlFetchApp . Однако для некоторых вызовов API, например, для вызова службы отправки SMS-сообщений, потребуются другие методы, например, POST или PUT .

Для иллюстрации использования вызовов POST с UrlFetchApp в следующем примере демонстрируется интеграция со Slack , приложением для совместного обмена сообщениями, для отправки сообщений Slack пользователям и группам Slack.

Настройте Slack

В этом руководстве предполагается, что вы уже зарегистрировали учетную запись Slack.

Как и в случае с OpenWeatherMap в предыдущем примере, для отправки сообщений необходимо получить токен. Slack предоставляет уникальный URL-адрес для отправки сообщений вашей команде, называемый Incoming Webhook .

Настройте входящий вебхук , нажав «Добавить интеграцию входящих вебхуков» и следуя инструкциям. В результате будет создан URL-адрес для отправки сообщений.

Сделайте POST-запрос

После настройки входящего веб-перехватчика для выполнения запроса POST достаточно использовать некоторые дополнительные свойства в параметре options переданном в UrlFetchApp.fetch :

  • method : как уже упоминалось, по умолчанию это GET , но здесь мы переопределяем его и устанавливаем POST .

  • payload : данные, отправляемые на сервер в рамках POST запроса. В этом примере Slack ожидает объект, сериализованный в формат JSON, как описано в документации Slack . Для этого используется метод JSON.stringify , а Content-Type задано значение application/json .

      // Change the URL for the one issued to you from 'Setting up Slack'.
  const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
  const slackMessage = {
    text: 'Hello, slack!'
  };

  const options = {
    method: 'POST',
    contentType: 'application/json',
    payload: JSON.stringify(slackMessage)
  };
  UrlFetchApp.fetch(SLACK_URL, options);

Расширенный пример Slack

В примере выше показан минимальный набор действий для включения входящих сообщений в Slack. Более подробный пример иллюстрирует создание и отправку отчёта об эффективности кампании группе, а также некоторые параметры форматирования и отображения.

Входящее сообщение

Более подробную информацию о сообщениях Slack см. в разделе «Форматирование сообщений» документации Slack.

Данные формы

В примере выше продемонстрировано использование строки JSON в качестве свойства payload для запроса POST .

В зависимости от формата payload UrlFetchApp использует разные подходы к построению запроса POST :

  • Если payload представляет собой строку, аргумент строки отправляется как тело запроса.

  • Когда payload представляет собой объект, например карту значений:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}

    Пары ключ/значение преобразуются в form-data:

    subject=Test&to=mail@example.com&body=Hello,+World!

    Также заголовок Content-Type для запроса устанавливается на application/x-www-form-urlencoded .

Некоторые API требуют использования данных формы при отправке POST-запросов, поэтому полезно помнить об автоматическом преобразовании объектов JavaScript в данные формы .

Базовая HTTP-аутентификация

Базовая HTTP-аутентификация — одна из простейших форм аутентификации, используемая многими API.

Аутентификация достигается путем присоединения закодированного имени пользователя и пароля к заголовкам HTTP каждого запроса.

Базовая HTTP-аутентификация

Создать запрос

Для создания аутентифицированного запроса необходимо выполнить следующие шаги:

  1. Сформируйте парольную фразу, соединив имя пользователя и пароль двоеточием, например, username:password .
  2. Кодируем парольную фразу с помощью Base64, например username:password становится dXNlcm5hbWU6cGFzc3dvcmQ= .
  3. Прикрепите к запросу заголовок Authorization в форме Authorization: Basic <encoded passphrase>

Следующий фрагмент иллюстрирует, как добиться этого в скриптах Google Ads:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

Базовые образцы аутентификации

Раздел примеров кода содержит два примера, иллюстрирующих использование базовой аутентификации HTTP:

Пливо

Plivo — это сервис, который упрощает отправку и получение SMS-сообщений через API. Этот пример иллюстрирует отправку сообщений.

  1. Зарегистрируйтесь в Plivo .
  2. Вставьте пример скрипта в новый скрипт в Google Ads.
  3. Замените значения PLIVO_ACCOUNT_AUTHID и PLIVO_ACCOUNT_AUTHTOKEN значениями из панели управления .
  4. Введите свой адрес электронной почты, указанный в скрипте для уведомления об ошибках.
  5. Чтобы использовать Plivo, необходимо либо приобрести номера, либо добавить их в пробную учётную запись. Добавьте номера Sandbox , которые можно использовать с пробной учётной записью.
  6. Добавьте номер, который будет указан в качестве отправителя, и номер получателя.
  7. Обновите PLIVO_SRC_PHONE_NUMBER в скрипте, указав один из только что зарегистрированных номеров в тестовой среде. Этот номер должен включать международный код страны, например, 447777123456 для номера в Великобритании.

Твилио

Twilio — ещё один сервис, упрощающий отправку и получение SMS-сообщений через API. Этот пример иллюстрирует отправку сообщений.

  1. Зарегистрируйтесь в Twillio .
  2. Вставьте пример скрипта в новый скрипт в Google Ads.
  3. Замените значения TWILIO_ACCOUNT_SID и TWILIO_ACCOUNT_AUTHTOKEN на значения, указанные на странице консоли учетной записи .
  4. Замените TWILIO_SRC_PHONE_NUMBER на номер с панели управления — это номер, авторизованный Twilio для отправки сообщений.

OAuth 1.0

Многие популярные сервисы используют OAuth для аутентификации. OAuth существует в нескольких вариантах и версиях.

В то время как при базовой HTTP-аутентификации у пользователя есть только одно имя пользователя и пароль, OAuth позволяет сторонним приложениям получать доступ к учётной записи и данным пользователя, используя учётные данные, специфичные для этого стороннего приложения. Кроме того, уровень доступа также будет зависеть от этого приложения.

Информацию об OAuth 1.0 см. в руководстве OAuth Core . В частности, см . раздел 6. Аутентификация с помощью OAuth . В полноценном трёхстороннем OAuth 1.0 процесс выглядит следующим образом:

  1. Приложение («Потребитель») получает токен запроса.
  2. Пользователь авторизует токен запроса.
  3. Приложение обменивает токен запроса на токен доступа.
  4. Для всех последующих запросов ресурсов токен доступа используется в подписанном запросе.

Для сторонних сервисов, использующих OAuth 1.0 без взаимодействия с пользователем (например, как того требуют скрипты Google Ads), шаги 1, 2 и 3 невозможны. Поэтому некоторые сервисы выдают токен доступа из своей консоли конфигурации, позволяя приложению напрямую перейти к шагу 4. Это называется односторонним OAuth 1.0.

OAuth1

OAuth 1.0 в скриптах Google Ads

В скриптах Google Ads каждый скрипт обычно интерпретируется как приложение. Через консоль/страницу настроек администрирования сервиса обычно необходимо:

  • Настройте конфигурацию приложения для представления сценария.
  • Укажите, какие разрешения предоставляются скрипту.
  • Получите ключ потребителя, секрет потребителя, токен доступа и секрет доступа для использования с односторонним OAuth.

OAuth 2.0

OAuth 2.0 используется в популярных API для предоставления доступа к пользовательским данным. Владелец учётной записи стороннего сервиса предоставляет определённым приложениям разрешение на доступ к пользовательским данным. Преимущества заключаются в следующем:

  • Не требуется предоставлять приложению свои учетные данные.
  • Можно контролировать, какие приложения будут иметь доступ к данным по отдельности и в каком объеме. (Например, доступ может быть предоставлен только для чтения или только к подмножеству данных.)

Чтобы использовать службы с поддержкой OAuth 2.0 в скриптах Google Ads, необходимо выполнить несколько шагов:

Вне вашего сценария

Предоставьте скриптам Google Ads доступ к вашим пользовательским данным через сторонний API . В большинстве случаев это потребует настройки приложения в консоли стороннего сервиса. Это приложение представляет собой ваш скрипт Google Ads.

Вы указываете, какие права доступа следует предоставить приложению Google Ads Script, и ему обычно присваивается идентификатор клиента. Это позволяет вам через OAuth 2 контролировать, какие приложения имеют доступ к вашим данным в стороннем сервисе, а также какие аспекты этих данных они могут просматривать или изменять.

В вашем сценарии

Авторизуйтесь на удалённом сервере . В зависимости от типа разрешения, предоставленного сервером, потребуется выполнить различный набор шагов, называемый потоком , но в конечном итоге все они приведут к выдаче токена доступа , который будет использоваться в этом сеансе для всех последующих запросов.

Выполняйте запросы к API . Передавайте токен доступа с каждым запросом.

Потоки авторизации

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

Поставщики API будут решать, какие типы грантов они принимают, и это будет определять, как пользователь будет выполнять интеграцию своего API.

Выполнение

Целью всех различных потоков OAuth является получение токена доступа, который затем можно использовать до конца сеанса для аутентификации запросов.

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

Общая схема использования: 

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

Предоставление учетных данных клиента

Предоставление учетных данных клиента — одна из простейших форм потока OAuth2, в которой приложение обменивается идентификатором и секретом, уникальными для приложения, в обмен на выдачу токена доступа с ограниченным сроком действия.

Учетные данные клиента

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

Грант на обновление токена

Предоставление токена обновления аналогично предоставлению учетных данных клиента, поскольку простой запрос к серверу вернет токен доступа , который можно использовать в сеансе.

Обновить токен

Получить токен обновления

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

Код авторизации

Использование OAuth Playground для получения токена обновления

Площадка OAuth2 предоставляет пользовательский интерфейс, который позволяет пользователю пройти процедуру предоставления кода авторизации для получения токена обновления.

Кнопка настроек в правом верхнем углу позволяет определить все параметры, используемые в потоке OAuth, включая:

  • Конечная точка авторизации : используется в качестве начала потока авторизации.
  • Конечная точка токена : используется с токеном обновления для получения токена доступа.
  • Идентификатор клиента и секрет : учетные данные для приложения.

Площадка OAuth

Обновить использование токена

После выполнения первоначальной авторизации сервисы могут выдать токен обновления, который затем можно использовать аналогично потоку учётных данных клиента. Ниже приведены два примера: 

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Пример Search Ads 360

Search Ads 360 — пример API, который можно использовать с токеном обновления. В этом примере скрипт генерирует и возвращает отчёт . Полную информацию о других доступных действиях см. в справке по Search Ads 360 API.

Создать сценарий
  1. Создайте новый проект в консоли API и получите идентификатор клиента, секретный код клиента и токен обновления, выполнив процедуру, описанную в руководстве по Search Ads 360 , убедившись, что API Search Ads 360 включен.
  2. Вставьте пример скрипта в новый скрипт в Google Ads.
  3. Вставьте пример библиотеки OAuth2 под листингом кода.
  4. Измените скрипт, включив в него правильные значения идентификатора клиента, секретного ключа клиента и токена обновления.

Пример API выполнения скриптов приложений

В этом примере показано выполнение функции в Apps Script с помощью API Apps Script Execution . Это позволяет вызывать Apps Script из скриптов Google Ads.

Создайте скрипт Apps Script

Создайте новый скрипт . Следующий пример выведет список 10 файлов с Диска: 

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Настройте скрипт приложения для выполнения
  1. Сохраните сценарий.
  2. Нажмите Ресурсы > Проект облачной платформы .
  3. Щелкните имя проекта, чтобы перейти к консоли API.
  4. Перейдите в раздел API и службы .
  5. Включите соответствующие API, в данном случае Drive API и Apps Script Execution API .
  6. Создайте учетные данные OAuth из пункта «Учетные данные» в меню.
  7. Вернувшись в скрипт, опубликуйте его для выполнения, выбрав Опубликовать > Развернуть как исполняемый файл API .
Создайте скрипт Google Ads
  1. Вставьте пример скрипта в новый скрипт в Google Ads.
  2. Кроме того, вставьте пример библиотеки OAuth2 под листингом кода.
  3. Измените скрипт, включив в него правильные значения идентификатора клиента, секретного ключа клиента и токена обновления.

Учетные записи служб

Альтернативой вышеуказанным типам грантов является концепция сервисных счетов .

Учётные записи служб отличаются от описанных выше тем, что они не используются для доступа к пользовательским данным: после аутентификации запросы выполняются учётной записью службы от имени приложения, а не от имени пользователя, который может владеть проектом. Например, если учётная запись службы использует API Диска для создания файла, этот файл будет принадлежать учётной записи службы и по умолчанию не будет доступен владельцу проекта.

Пример API естественного языка Google

API естественного языка обеспечивает анализ настроений и сущностей текста.

Этот пример иллюстрирует расчёт тональности текста объявления, включая заголовок или описание. Это позволяет оценить позитивность и значимость сообщения: что лучше: « Мы продаём торты» или «Мы продаём лучшие торты в Лондоне». Купите сегодня!

Настройте сценарий
  1. Создайте новый проект в API Console
  2. Включить API естественного языка
  3. Включить выставление счетов за проект.
  4. Создайте учетную запись сервиса . Загрузите JSON-файл с учетными данными.
  5. Вставьте пример скрипта в новый скрипт в Google Ads.
  6. Кроме того, вставьте пример библиотеки OAuth2 под листингом кода.
  7. Замените необходимые значения:
    • serviceAccount : Адрес электронной почты учетной записи службы, например xxxxx@yyyy.iam.gserviceaccount.com .
    • key : ключ из JSON-файла, загруженного при создании учётной записи службы. Начинается с -----BEGIN PRIVATE KEY... и заканчивается ...END PRIVATE KEY-----\n .

Ответы API

API могут возвращать данные в различных форматах. Наиболее известные из них — XML и JSON.

JSON

JSON обычно проще использовать в качестве формата ответа, чем XML. Однако некоторые проблемы всё же могут возникнуть.

Проверка ответа

Получив успешный ответ на вызов API, следующим типичным шагом является преобразование JSON-строки в объект JavaScript с помощью JSON.parse . На этом этапе разумно обработать случай, когда парсинг завершается неудачей : 

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

Кроме того, если API не находится под вашим контролем, учтите, что структура ответа может измениться, а свойства могут больше не существовать: 

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

Проверка

XML по-прежнему остаётся популярным форматом для создания API. Ответ на вызов API можно проанализировать с помощью метода parse сервиса XmlService : 

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

Хотя XmlService.parse обнаруживает ошибки в XML и выдает соответствующие исключения, он не предоставляет возможности проверки XML на соответствие схеме.

Корневой элемент

При успешном разборе XML-документа корневой элемент получается с помощью метода getRootElement() : 

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

Пространства имен

В следующем примере API Sportradar используется для получения результатов футбольных матчей. XML-ответ имеет следующий формат: 

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

Обратите внимание, как пространство имён указано в корневом элементе. В связи с этим необходимо:

  • Извлечь атрибут пространства имен из документа.
  • Используйте это пространство имен при обходе и доступе к дочерним элементам.

В следующем примере показано, как получить доступ к элементу <matches> в приведенном выше фрагменте документа: 

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

Получить значения

Приведем пример из футбольного расписания: 

<match status="..." category="..." ... >
  ...
</match>

Атрибуты могут быть извлечены, например: 

const status = matchElement.getAttribute('status').getValue();

Текст, содержащийся в элементе, можно прочитать с помощью getText() , но при наличии нескольких дочерних элементов текстового типа они будут объединены. Если вероятность наличия нескольких дочерних элементов текстового типа высока, рассмотрите возможность использования метода getChildren() и итерации по каждому дочернему элементу.

Пример Sportradar

Этот полный пример Sportradar иллюстрирует получение информации о футбольных матчах, в частности, о матчах английской Премьер-лиги. Soccer API — один из множества спортивных каналов, предлагаемых Sportradar.

Создайте учетную запись Sportradar
  1. Перейдите на сайт разработчиков Sportradar
  2. Зарегистрируйте пробную учетную запись .
  3. После регистрации войдите в свою учетную запись.
  4. После входа в систему перейдите в раздел MyAccount .

Sportradar разделяет разные виды спорта на отдельные API. Например, вы можете приобрести доступ к API для футбола, но не к API для тенниса. Каждое созданное вами приложение может иметь разные виды спорта и разные ключи.

  1. В разделе «Приложения» нажмите «Создать новое приложение» . Введите имя и описание приложения, не обращая внимания на поле «Веб-сайт».
  2. Выберите только « Выдать новый ключ для Soccer Trial Europe v2» .
  3. Нажмите «Зарегистрировать заявку» .

В случае успеха вы должны увидеть страницу с вашим новым ключом API.

  1. Вставьте пример скрипта в новый скрипт в Google Ads.
  2. Замените ключ API в листинге на ключ, полученный выше, и отредактируйте поле адреса электронной почты.

Поиск неисправностей

При работе со сторонними API ошибки могут возникать по ряду причин, например:

  • Клиенты отправляют запросы серверу в формате, не ожидаемом API.
  • Клиенты ожидают получить ответ в формате, отличном от полученного.
  • Клиенты используют недействительные токены или ключи, или значения, оставленные в качестве заполнителей.
  • Клиенты достигли лимитов использования.
  • Клиенты предоставляют неверные параметры.

Во всех этих и других случаях первым шагом в определении причины проблемы является изучение деталей ответа, вызвавшего ошибку.

Анализ ответов

По умолчанию любой ответ, возвращающий ошибку ( код статуса 400 или выше), будет обработан движком скриптов Google Ads.

Чтобы предотвратить такое поведение и разрешить проверку ошибок и сообщений об ошибках, установите для свойства muteHttpExceptions необязательных параметров значение UrlFetchApp.fetch . Например: 

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

Общие коды статуса

  • 200 OK означает успешное выполнение. Если ответ не содержит ожидаемых данных, учтите следующее:

    • Некоторые API позволяют указать, какие поля и/или формат ответа использовать. Подробности см. в документации API.
    • API может содержать несколько ресурсов, к которым можно обратиться. Обратитесь к документации, чтобы определить, какой другой ресурс может быть более подходящим и вернет вам необходимые данные.
    • API мог измениться с момента написания кода. За разъяснениями обратитесь к документации или к разработчику.

  • 400 Bad Request обычно означает, что в формате или структуре запроса, отправленного на сервер, есть ошибки. Проверьте запрос и сравните его со спецификациями API, чтобы убедиться в его соответствии ожиданиям. Подробнее о проверке запросов см. в разделе Проверка запросов.

  • 401 Unauthorized обычно означает, что API вызывается без предоставления или успешного выполнения авторизации.

    • Если API использует базовую авторизацию, убедитесь, что заголовок Authorization формируется и предоставляется в запросе.
    • Если API использует OAuth 2.0, убедитесь, что токен доступа получен и предоставляется как токен на предъявителя .
    • Для любых других вариантов авторизации убедитесь, что предоставлены необходимые учетные данные для запроса.

  • 403 Forbidden указывает, что у пользователя нет разрешения на запрашиваемый ресурс.

    • Убедитесь, что пользователю предоставлены необходимые разрешения, например, предоставление пользователю доступа к файлу в запросе на файл.

  • 404 Not Found означает, что запрошенный ресурс не существует.

    • Проверьте правильность URL-адреса, используемого для конечной точки API.
    • При извлечении ресурса проверьте, существует ли ресурс, на который ссылается ссылка (например, существует ли файл для API на основе файлов).

Проверка запросов

Проверка запросов полезна, когда ответы API указывают на то, что запрос неправильно сформирован, например, код статуса 400. Для проверки запросов UrlFetchApp есть метод, сопутствующий методу fetch() , называемый getRequest()

Вместо отправки запроса на сервер этот метод формирует запрос, который должен был быть отправлен, а затем возвращает его. Это позволяет пользователю проверить элементы запроса и убедиться в его корректности.

Например, если данные формы в вашем запросе состоят из множества строк, объединенных вместе, ошибка может быть связана с функцией, созданной вами для генерации этих данных. В простейшем случае: 

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

позволит вам проверить элементы запроса.

Журнал запросов и ответов

Чтобы облегчить весь процесс проверки запросов и ответов к стороннему API, можно использовать следующую вспомогательную функцию в качестве замены UrlFetchApp.fetch() для регистрации как запросов, так и ответов.

  1. Замените все экземпляры UrlFetchApp.fetch() в вашем коде на logUrlFetch() .

  2. Добавьте следующую функцию в конец вашего скрипта. 

    function logUrlFetch(url, opt_params) {
  const params = opt_params || {};
  params.muteHttpExceptions = true;
  const request = UrlFetchApp.getRequest(url, params);
  console.log('Request:       >>> ' + JSON.stringify(request));
  const response = UrlFetchApp.fetch(url, params);
  console.log('Response Code: <<< ' + response.getResponseCode());
  console.log('Response text: <<< ' + response.getContentText());
  if (response.getResponseCode() >= 400) {
    throw Error('Error in response: ' + response);
  }
  return response;
}

При выполнении скрипта подробная информация обо всех запросах и ответах записывается в консоль, что упрощает отладку.