Сторонние API

Скрипты Google Рекламы можно интегрировать с данными и сервисами из сторонних 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());

В результате выполнения этого кода в окне журнала скриптов Google Рекламы появится длинная строка текста в формате JSON.

Теперь нужно преобразовать эти данные в формат, который можно использовать в скрипте.

Данные 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, который позволяет отправлять сообщения вашей команде. Он называется входящим вебхуком.

Настройте входящий вебхук, нажав Add Incoming WebHooks Integration (Добавить интеграцию входящих вебхуков) и следуя инструкциям. В результате вы получите URL, который нужно использовать для обмена сообщениями.

Как выполнить запрос POST

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

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

  • payload – данные, которые будут отправлены на сервер в рамках запроса POST. В этом примере Slack ожидает объект, сериализованный в формате JSON, как описано в документации Slack. Для этого используется метод [JSON.stringify][json-stringify-url], а для 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 Рекламы:

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

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

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

Twilio

Twilio – ещё один сервис, который упрощает отправку и получение SMS-сообщений с помощью API. В этом примере показано, как отправлять сообщения.

  1. Зарегистрируйтесь в Twillio.
  2. Вставьте пример скрипта в новый скрипт в Google Рекламе.
  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 Рекламы), шаги 1, 2 и 3 выполнить невозможно. Поэтому некоторые сервисы выдают токен доступа из своей консоли конфигурации, позволяя приложению сразу перейти к шагу 4. Этот метод называется односторонним OAuth 1.0.

OAuth1

OAuth 1.0 в скриптах Google Рекламы

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

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

OAuth 2.0

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

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

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

За пределами скрипта

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

Вы указываете, какие права доступа должны быть предоставлены приложению скриптов Google Рекламы, и обычно ему назначается идентификатор клиента. Это позволяет вам с помощью 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);

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

[Предоставление учетных данных клиента][client-credentials-rfc] – это одна из наиболее простых форм процесса 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

Предоставление токена обновления

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

Токен обновления

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

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

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

Как получить токен обновления с помощью OAuth Playground

OAuth2 Playground – это интерфейс, который позволяет пользователю пошагово пройти процесс предоставления кода авторизации, чтобы получить токен обновления.

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

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

  • Идентификатор клиента и секретный код – учетные данные приложения.

    OAuth Playground

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

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

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

Пример для Поисковой рекламы 360

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

Создайте скрипт
  1. Создайте проект в консоли Google Cloud и получите идентификатор клиента, секретный код клиента и токен обновления, следуя инструкциям в руководстве по Поисковой рекламе 360. Убедитесь, что вы включили Search Ads 360 API.
  2. Вставьте [пример скрипта][search-ads-360-example] в новый скрипт в Google Рекламе.
  3. Вставьте [пример библиотеки OAuth2][oauth20-library-example] под списком кодов.
  4. Измените скрипт, указав правильные значения идентификатора клиента, секретного кода клиента и токена обновления.

Пример Apps Script Execution API

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

Как создать скрипт 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;
}
Как настроить Apps Script для выполнения
  1. Сохраните скрипт.
  2. Нажмите Resources (Ресурсы) > Cloud Platform project (Проект Cloud Platform).
  3. Нажмите на название проекта, чтобы перейти в консоль Google Cloud.
  4. Перейдите в раздел API и сервисы.
  5. Включите нужные API. В данном случае это Drive API и Apps Script Execution API.
  6. Создайте учетные данные OAuth, выбрав в меню пункт Учетные данные.
  7. Вернитесь к скрипту и опубликуйте его для выполнения, выбрав Publish (Опубликовать) > Deploy as API Executable (Развернуть как исполняемый файл API).
Как создать скрипт Google Рекламы
  1. Вставьте пример скрипта в новый скрипт в Google Рекламе.
  2. Кроме того, вставьте [пример библиотеки OAuth2][oauth20-library-example] под списком кодов.
  3. Измените скрипт, указав правильные значения идентификатора клиента, секретного кода клиента и токена обновления.

Сервисные аккаунты

Альтернативой типам предоставления доступа являются сервисные аккаунты.

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

Пример Google Natural Language API

[Natural Language API][natural-language-api-docs] позволяет выполнять [анализ тональности текста][sentiment-analysis-api-docs] и [анализ объектов][entity-analysis-api-docs] в тексте.

В этом примере показано, как рассчитать [тональность][sentiment-api-docs] текста объявления, включая заголовок и описание. Это позволяет оценить , насколько позитивно сообщение и какова его значимость. Что лучше: Мы продаем торты или Мы продаем лучшие торты в Лондоне? Купите сегодня!?

Как настроить скрипт
  1. Создайте новый проект в консоли Google Cloud.
  2. Включите [Natural Language API][natural-language-api].
  3. Включите платежные функции для проекта.
  4. [Создайте сервисный аккаунт][create-service-account]. Скачайте JSON-файл с учетными данными.
  5. Вставьте [пример скрипта][natural-language-example] в новый скрипт в Google Рекламе.
  6. Кроме того, вставьте [пример библиотеки OAuth2][oauth20-library-example] под списком кодов.
  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

XmlService позволяет скриптам анализировать и извлекать данные из тел ответов XML.

Проверка

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

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();

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

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

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

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

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

В примере ниже показано, как получить доступ к элементу <schedule> и найти его дочерние элементы <sport_event> в приведенном выше фрагменте документа.

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

Получение значений

Предположим, есть расписание футбольных матчей:

<sport_event_status status="..." ... />

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

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

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

Пример Sportradar

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

Как настроить аккаунт Sportradar
  1. Перейдите на сайт Sportradar для разработчиков.
  2. Зарегистрируйте пробный аккаунт.
  3. После регистрации войдите в аккаунт.
  4. Войдите в аккаунт и перейдите в раздел My Account (Мой аккаунт).

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

  1. В разделе Applications (Приложения) нажмите Create a new Application (Создать приложение). Укажите название и описание приложения. Поле "Веб-сайт" можно оставить пустым.
  2. Выберите только Выпустить новый ключ для Soccer Trial Europe v2.
  3. Нажмите Register Application (Зарегистрировать приложение).

После этого откроется страница с новым ключом API.

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

Устранение неполадок

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

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

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

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

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

Чтобы этого не происходило и вы могли изучить ошибку и сообщение об ошибке, задайте для свойства 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(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;
}

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities