Сторонние API

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

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

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

Получение данных с помощью 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.

Как и в случае с 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 Рекламы:

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

Пливо

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

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

Твилио

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

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

ОАутентификация 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.

ОАут1

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

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

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

ОАутентификация 2.0

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

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

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

За пределами вашего сценария

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

Вы указываете, какие права доступа следует предоставить приложению 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

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

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

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

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

В этом примере показано выполнение функции в Apps Script с использованием Apps Script Execution API . Это позволяет вызывать скрипт Apps из скриптов 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;
}
Настройка скрипта приложений для выполнения
  1. Сохраните сценарий.
  2. Нажмите Ресурсы > Проект Cloud Platform .
  3. Щелкните имя проекта, чтобы перейти к консоли API.
  4. Перейдите к API и службам .
  5. Включите соответствующие API, в данном случае Drive API и Apps Script Execution API .
  6. Создайте учетные данные OAuth из пункта «Учетные данные» в меню.
  7. Вернитесь к своему сценарию и опубликуйте его для выполнения, выбрав «Опубликовать» > «Развернуть как исполняемый файл API» .
Создайте скрипт Google Рекламы
  1. Вставьте образец скрипта в новый скрипт Google Рекламы.
  2. Кроме того, вставьте образец библиотеки OAuth2 под листинг кода.
  3. Измените сценарий, чтобы он содержал правильные значения идентификатора клиента, секрета клиента и токена обновления.

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

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

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

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

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

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

Настройте сценарий
  1. Создайте новый проект в консоли API.
  2. Включить API естественного языка
  3. Включите биллинг для проекта.
  4. Создайте учетную запись службы . Загрузите JSON-файл учетных данных.
  5. Вставьте образец скрипта в новый скрипт Google Рекламы.
  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 иллюстрирует получение подробной информации о футбольных матчах, в частности о матчах английской Премьер-лиги. Soccer API – это один из множества спортивных каналов, предлагаемых Sportradar.

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

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

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

В случае успеха на экране должна появиться страница с вашим новым ключом 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()

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

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

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

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