Настройка инструмента Call API

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

Инструмент Call API позволяет управлять публичными запросами API, которые совершаются в рамках автоматизированных рабочих процессов Bridge. Этот модуль состоит из двух основных компонентов. 

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

• Модуль Make API Call (Создание вызовов API), который использует данные профиля и предоставленную вами информацию для совершения вызова к системному API.

   

Совет по работе с построителем Bridge

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

Поля модуля API Call

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

Base URL (Базовый URL-адрес)

Это поле содержится в профиле и представляет собой неизменяемую часть URL-адреса API. Для Smartsheet используйте базовый URL https://api.smartsheet.com/2.0/.

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

Это поле содержится в модуле Make API Call и указывает действие, которое вы хотите выполнить (например, отсортировать таблицу). Здесь можно добавить необходимые ссылки на данные из триггеров Bridge.

Ниже приведены примеры настройки для статических и динамических данных.

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

Method (Метод)

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

• GET. Импорт данных в рабочий процесс Bridge путём получения строки из таблицы.
• POST. Создание объекта. Например, добавление строки в таблицу.
• PUT. Обновление объекта. Например, обновление строки таблицы.
• DELETE. Удаление объекта. Например, удаление строки из таблицы.

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

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

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

Form Parameters (Параметры формы)

Параметры формы также называются Query Parameters (Параметры запроса) или Arguments (Аргументы). Это дополнительные элементы, которые можно указать в запросе. Их можно задать в модуле Make API Call.

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

Body (Тело)

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

Отправка параметров формы переопределяет все данные, указанные в поле Body (Тело).

В вызове API Sort Sheet (Сортировать таблицу) тело будет выглядеть следующим образом: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. В приведённом выше примере в тело можно подставить значение одного из этих типов:

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

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

Возвращаемые данные

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

Теперь вы знаете, какие поля используются при настройке модулей Call API Profile и Make API Call. Далее описывается, как настроить и использовать эту утилиту.

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

• Таблица:
  • идентификатор таблицы;
  • столбец, при изменении которого должен запускаться рабочий процесс Bridge.
• Bridge:
  • интеграция со Smartsheet;
  • триггер рабочего процесса Bridge: Smartsheet > When Column Values are Changed (При изменении значений столбцов);
  • модули рабочих процессов Bridge: Make API Call.
• Ключ API Smartsheet. Подробнее о том, как сгенерировать ключ API для Smartsheet. 

Начало работы

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

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

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

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

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

Вот как должен выглядеть готовый рабочий процесс. 

Brandfolder Image

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

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

1. Выберите модуль Trigger (Триггер).
2. Выберите страницу Integrations (Интеграции) в разделе Integrations, чтобы открыть панель Integration в новой вкладке.

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

   Используйте опцию Connected (Подключены) под логотипом Bridge, чтобы получить список только тех интеграций, которые прошли аутентификацию для данного рабочего пространства.

4. Разверните строку Triggers (Триггеры).
5. Чтобы создать новый триггер, нажмите значок плюса.
6. Заполните следующие поля.
   • Trigger Name (Имя триггера). Создайте пользовательскую метку для своего триггера.
   • Sheet ID (Идентификатор таблицы). Укажите идентификатор таблицы, которую вы хотите отсортировать.
   • Event Type (Тип события). Выберите When Column Values are Changed (При изменении значений столбцов). 
   • Column Name or ID (Имя или идентификатор столбца). Введите имя столбца Smartsheet, на изменения которого будет реагировать рабочий процесс. Например, если вы хотите сортировать строки таблицы при каждом изменении приоритета, введите имя столбца, содержащего приоритеты.
   • Select Workflow (Выбор рабочего процесса). Выберите новый рабочий процесс, который вы только что создали, из выпадающего списка.
7. Нажмите кнопку Save (Сохранить).
8. В разделе Trigger скопируйте идентификатор столбца.
   • Идентификатор столбца будет доступен после сохранения триггера рабочего процесса.
9. Вставьте его в блокнот или другой текстовый редактор. Идентификатор столбца понадобится вам на следующем этапе. 

10. Вернитесь к рабочему процессу.
     

    Если вы хотите вернуться на исходную вкладку, обновите страницу, чтобы увидеть триггер.

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

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

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

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

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

1. Войдите в свою учётную запись Bridge.
2. Перейдите на вкладку Integrations (Интеграции).
3. Выберите утилиту Call API.

4. Выберите Add to Profiles (Добавить в профили).

   Brandfolder Image

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

10. Вернитесь к рабочему процессу.

     

Совет по работе с построителем Bridge

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

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

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

1. В модуле Make API Call выберите нужный профиль из раскрывающегося списка.
2. В поле Endpoint (Конечная точка) укажите часть URL, которая не была включена в поле Base URL (Базовый URL) в профиле.
   • В этом примере мы использовали sheets/sheet_id_or_data_reference_here/sort.
3. Заполните следующие поля. Обратите внимание, что не все из них могут понадобиться.
   • Установите в поле Method (Метод) значение POST.
   • В поле HTTP Request Body (Тело HTTP-запроса) значение будет выглядеть следующим образом: {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}.
   • Form Parameters (Параметры формы) — при необходимости (в данном рабочем процессе они не используются).

4. Сохраните изменения.

   Brandfolder Image

   

   
    

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

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

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

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

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

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

Вот как ещё можно настроить этот рабочий процесс.

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

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

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