Сторонние 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 .

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

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

Настройте Slack

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

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

Для настройки входящего веб-перехватчика нажмите «Добавить интеграцию входящих веб-перехватчиков» и следуйте инструкциям. В результате процесса будет сгенерирован 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!'}

    Пары «ключ-значение» преобразуются в данные формы:

    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. Зарегистрируйтесь в Twilio .
  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, и обычно ему присваивается идентификатор клиента. Это позволяет вам, с помощью OAuth 2.0, контролировать, какие приложения имеют доступ к вашим данным в стороннем сервисе, а также какие аспекты этих данных они могут видеть или изменять.

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

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

Выполняйте 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 Playground

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

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

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

Пример Search Ads 360

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

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

Пример использования API выполнения скриптов Apps Script

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

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

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

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, в данном случае API Google Drive и API выполнения скриптов Apps Script .
  6. Создайте учетные данные OAuth, выбрав пункт « Учетные данные» в меню.
  7. Вернитесь в свой скрипт и опубликуйте его для выполнения, выбрав «Опубликовать» > «Развернуть как исполняемый файл API» .
Создайте скрипт для Google Ads.
  1. Вставьте пример скрипта в новый скрипт в Google Ads.
  2. Кроме того, вставьте пример библиотеки OAuth2 под листингом кода.
  3. Внесите изменения в скрипт, указав правильные значения идентификатора клиента, секретного ключа клиента и токена обновления.

Служебные счета

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

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

Пример использования API Google для обработки естественного языка

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

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

Настройте скрипт
  1. Создайте новый проект в консоли API.
  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.parse для преобразования строки JSON в объект JavaScript. На этом этапе целесообразно обработать случай, когда парсинг не удался : 

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. После входа в систему перейдите в раздел «Мой аккаунт» .

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, убедитесь, что токен доступа получен и предоставляется в виде токена Bearer .
    • При любых других вариантах авторизации убедитесь, что предоставляются необходимые учетные данные для запроса.

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

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

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

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

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

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

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

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

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;
}

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