Утилиты Bridge: API вызовов

Утилита Call API позволяет управлять публичными вызовами API в рабочих процессах автоматизации в Bridge. Он состоит из двух основных компонентов: 

• Профили: сохраните информацию о системных API, к которым вы хотите подключить свои рабочие процессы. 

• Модуль Make API Call использует данные профиля и конкретные сведения, которые вы предоставляете для вызова API к системному API.

  Для этого требуются навыки работы с API и написания кода.

Совет строителю мостов

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

Модуль Make API Call 

Это единственный модуль утилиты, содержащий следующие поля:

Endpoint (Конечная точка)

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

• Значение статического идентификатора — формат URL-адреса для этого типа данных выглядит следующим образом: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. В этом URL-адресе необходимо указать идентификатор таблицы, чтобы вызов API всегда сортировал именно эту таблицу. 
• Справочник по данным журнала динамического запуска — формат URL-адреса этих данных выглядит следующим образом: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Однако вместо добавления идентификатора листа необходимо добавить ссылку на данные листа из журнала запуска. Это может пригодиться, если рабочий процесс Bridge срабатывает при изменениях нескольких таблиц или выполняет импорт данных из нескольких таблиц. При использовании этого типа URL-адреса вызов API сортирует определенную таблицу, указанную в этом URL-адресе.

Method (Метод)

Метод определяет тип операций, которые вы хотите выполнить. Определите метод для каждого вызова API в модуле Make API Call. Большинство API указывают метод, необходимый для данной конечной точки API. Например, в Smartsheet вы будете использовать следующие методы.

• GET: Внесите данные в рабочий процесс Bridge, «получив» строку из таблицы.
• СООБЩЕНИЕ: Создайте что-нибудь. Например, вы можете добавить строку таблицы.
• PUT: Обновите что-нибудь. Например, обновление строки таблицы.
• УДАЛИТЬ: удалить что-то. Например, обновление строки таблицы.

Headers (Заголовки)

Поле Headers — это значения, необходимые для создания запроса, и пары "ключ — значение". Обычно они используются для работы с параметрами авторизации (разрешениями). Например, в вызовах Smartsheet у вас будет ключ Header под названием Authorization со значением Bearer [Введите свой токен API].

В профиле можно настроить заголовки, необходимые для каждого вызова системы. В рабочем процессе модуль Make API Call позволяет настроить дополнительные заголовки для определенных действий. 

Параметры формы 

Параметры формы также можно назвать параметрами запроса или аргументами. Это дополнительные элементы, которые можно указать в запросе. Их можно задать в модуле Make API Call.

В качестве примера можно привести разбиение выдачи вызова Smartsheet на страницы, чтобы в результаты попало только определённое количество элементов. Например, вы хотите получить только первую страницу отчёта, содержащего 20 000 строк.

Тело HTTP-запроса

В теле содержатся данные запроса, которые необходимо отправить. Обычно они представлены в формате JSON.

Отправка параметров формы переопределяет любые данные Body.

При вызове API сортировки текст будет выглядеть следующим образом: {"sortCriteria»: [{"columnID»: {SmartSheetColumnID}, «направление»: «ПО УБЫВАНИЮ"}]}. В приведённом выше примере в поле "Тело" можно подставить значение одного из этих типов:

• статическое значение определённого столбца таблицы;
• динамическая ссылка на данные журнала запуска, где отображается идентификатор столбца. 

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

Результат

Если API-ответчик отправит в качестве результата объект JSON, он будет сохранён в журнале запуска. Это позволяет ссылаться на возвращенные данные позже в рабочем процессе.

Что нужно для начала работы

• Таблица: 
  • Идентификатор листа
  • Столбец, который при изменении строк запускает рабочий процесс Bridge на
• Bridge
  • интеграция со Smartsheet;
  • триггер рабочего процесса Bridge: Smartsheet > When Column Values are Changed;
  • Модуль Bridge: Утилиты > API вызовов > Вызов API
• Ключ API Smartsheet.

Чтобы создать этот рабочий процесс в Bridge, аутентифицируйте интеграцию Smartsheet для своего рабочего пространства Bridge. 

При построении рабочего процесса держите таблицу, документацию по API Smartsheet и рабочий процесс Bridge открытыми в трёх отдельных вкладках. Это облегчит работу.

Шаг 1. Построение базовой модели рабочего процесса

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

1. Создайте новый рабочий процесс в Bridge. 
2. Используйте панель в построителе рабочих процессов, чтобы добавить модуль Make API Call.
3. Сохраните рабочий процесс.

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

Brandfolder Image

Настройка триггера рабочего процесса

1. Выберите модуль Trigger.
2. В разделе Интеграции выберите страницу интеграции.

3. Найдите Smartsheet в списке интеграций.

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

4. Разверните строку «Триггеры».
5. Чтобы создать новый триггер, выберите Добавить в триггеры.
6. Заполните следующие поля.
   • Имя триггера: создайте собственную метку для триггера.
   • Идентификатор листа: вставьте идентификатор листа (листа, который вы хотите отсортировать).
   • Тип события: выберите при изменении значений столбцов. 
   • Имя или идентификатор столбца: введите имя столбца Smartsheet, на который вы хотите ответить. Например, если вы собираетесь сортировать строки в таблице при каждом изменении приоритета, введите имя приоритетного столбца.
   • Выберите рабочий процесс: выберите новый рабочий процесс, который вы только что создали, из выпадающего списка.
7. Выберите «Сохранить».
8. Скопируйте идентификатор столбца в информации о триггере. После сохранения триггера рабочего процесса идентификатор столбца станет доступен в информации о триггере.
9. Вставьте его в Блокнот или любой текстовый процессор. Идентификатор столбца понадобится вам на следующем этапе. 
10. Вернитесь к рабочему процессу.

Получение информации о вызове API

Этот рабочий процесс изменяет значение в столбце приоритета триггера таблицы. Как только рабочий процесс обнаружит триггер (-ы), он выполнит необходимые действия с той же таблицей. Для заполнения модулей Smartsheet мы используем ссылки на данные среды выполнения (Run Log) из триггера.

Для этого рабочего процесса необходимо вызвать API в конечную точку Smartsheet Sort Sheet. Используйте документацию по API Smartsheet, чтобы изменить образец запрос на cURL.

Шаг 2. Создание первого профиля

Профили позволяют сохранять ключевую информацию о системных API, к которым вы хотите подключить свои рабочие процессы. При выборе профиля в модуле Make API Call часть информации, необходимой для совершения API-вызова, уже будет настроена. 

1. Перейдите на вкладку Интеграции.
2. Выберите утилиту Call API.
3. Разверните раздел «Профили» на вкладке «Профили».

4. Выберите «Добавить в профили».

   Brandfolder Image

   
5. Введите имя профиля. Имя каждого профиля должно быть уникальным.
6. Добавьте базовый URL-адрес системного API, к которому вы хотите подключиться.  Базовый URL-адрес Smartsheet — https://api.smartsheet.com/2.0/
7. В разделе «Секретные заголовки» добавьте любые заголовки, содержащие токены или секретную информацию, например токены API.
   • Например, в вызовах Smartsheet обычно используется ключ Header под названием Authorization со значением Bearer [Введите свой токен API].
8. В разделе «Заголовки» добавьте все заголовки, которые должны быть включены во все вызовы API, выполняемые с помощью этого профиля.
   • В этом примере мы использовали Content-Type в качестве заголовка со значением application/json.
9. Выберите «Сохранить».
10. Вернитесь к рабочему процессу.

Совет строителю мостов

Базовый URL — это часть URL-адреса системного API, которая остаётся неизменной независимо от действий, выполняемых в этой системе. Конечная точка в модуле Make API Call позволяет указать конкретные сведения и действия, которые вы выполняете при этом вызове API.

Пример. Мы используем API Smartsheet для сортировки таблицы. Базовый URL-адрес нашего профиля Smartsheet API — https://api.smartsheet.com/2.0, а в модуле мы выполняем специальную операцию по сортировке определенной таблицы, поэтому в поле Endpoint модуля необходимо указать sheets/sheet_id_or_data_reference_here/sort.

Шаг 3. Настройка модуля Make API Call в рабочем процессе

1. В модуле Make API Call выберите нужный профиль API для использования в раскрывающемся списке.
2. В поле Endpoint включите часть поля URL, которая не была добавлена в поле Base URL в профиле.
   • В этом примере мы использовали sheets/sheet_id_or_data_reference_here/sort.
3. Заполните следующие поля. Обратите внимание, что не все из них могут понадобиться.
   • Задайте для метода значение POST.
   • В поле Текст запроса HTTP текст будет выглядеть следующим образом: {"sortCriteria»: [{"columnId»: column_id_here, «направление»: «ПО ВОЗРАСТАНИЮ"}]}
   • Параметры формы (если используются — не используются в данном рабочем процессе)

4. Save your changes.

   Brandfolder Image

   

Шаг 4. Тестирование рабочего процесса

1. Откройте нужную таблицу. 
2. Измените значение в столбце приоритетов. 
3. Сохраните таблицу. 

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

Дополнительные настройки модуля

• Модуль Make API Call возвращает все вызовы API в виде объектов JSON. Если вам нужно, чтобы ответ возвращался в виде строки, вы можете установить флажок Return raw response в разделе Дополнительные настройки модуля.
• Если вам необходимо добавить дополнительные заголовки для определенного вызова, скопируйте их в раздел Заголовки HTTP-запроса.

Альтернативные варианты для этого рабочего процесса

• Триггер из таблицы или столбца, отличного от того, который вы хотите отсортировать. Для этого потребуется изменить сведения в вызове API в соответствии с таблицей и столбцом, который следует отсортировать. 
• Добавьте условие к сорту. После запуска рабочего процесса используйте соединительный модуль для оценки значения столбца и выполните различные действия в зависимости от изменения, внесенного в столбец «Приоритет» (например, если приоритет равен 0, переместите строку с листа, а если приоритет равен 1, отсортируйте лист).
• Используйте триггер «Расписание». При использовании этого триггера вам не придётся реагировать на изменения, так как рабочий процесс будет сортировать таблицу раз в день, раз в неделю или раз в месяц.

Использование инструментов модуля Call API в различных решениях

• Профили применяются к рабочему пространству, поэтому все рабочие процессы в вашем рабочем пространстве могут использовать один и тот же профиль во всех используемых модулях Make API Call.
• Если необходимо отредактировать данные профиля, поскольку изменились разрешения пользователя или параметры системного API, достаточно внести корректировки в одном месте и применить их к рабочим процессам в рабочем пространстве, использующим данный профиль.
• Для каждого дополнительного системного API, к которому нужно подключиться, можно настроить новый уникальный профиль, как описано в первой части этого руководства.
• Модуль Make API Call успешно работает, если он получает какой-либо ответ от целевого API, в том числе если он получает сообщение об ошибке. Это поможет вам в дальнейшем определить пути неожиданных ответов от API в рабочем процессе (например, если вызов API возвращает ошибку, вы можете отправить обновление в строку с сообщением о возникшей проблеме). Если вы предпочитаете останавливать рабочий процесс, если API возвращает ошибку, вы можете установить флажок в разделе «Дополнительные настройки» модуля.