Что такое REST API в Jira: Как использовать REST API и защитить API ключ Jira

Jira, универсальная платформа от Atlassian для отслеживания задач и управления проектами, стала незаменимым инструментом для бесчисленных команд разработчиков по всему миру. Хотя ее удобный интерфейс позволяет легко управлять проектами и отслеживать задачи, истинная сила Jira кроется в ее обширных возможностях настройки и интеграции. Центральное место здесь занимает REST API Jira, который открывает мир возможностей для автоматизации задач, построения кастомных приложений и бесшовной интеграции Jira с другими инструментами в вашей экосистеме разработки. В этом всеобъемлющем руководстве мы глубоко погрузимся в REST API Jira, изучим его возможности и пройдем через практические примеры, которые помогут вам начать работу.

Ключевые выводы: REST API Jira - это универсальный инструмент для автоматизации задач, построения кастомных приложений и интеграции Jira с другими инструментами разработки как в облачной, так и в серверной/дата-центр версиях. Он предлагает широкий спектр возможностей, включая управление задачами, массовые операции и пользовательскую отчетность, с поддержкой таких расширенных функций, как пагинация и раскрытие данных. Хотя между версиями есть некоторые различия, основная функциональность API остается постоянной, позволяя командам эффективно настраивать Jira под свои конкретные потребности и интегрировать ее в свою экосистему разработки.

Что такое API Jira?

По своей сути, API (Application Programming Interface) - это набор протоколов и инструментов, которые определяют, как программные компоненты должны взаимодействовать. В контексте Jira API позволяет внешним приложениям взаимодействовать с Jira программным путем, обеспечивая получение и манипулирование данными, а также выполнение действий внутри Jira. Jira предоставляет два типа API:

Что такое Java API

Java API Jira - это мощный инструмент для разработчиков, создающих кастомные приложения или плагины для Jira. Он обеспечивает прямой доступ к базовым Java-объектам и методам сервера Jira, позволяя глубоко интегрировать и настраивать. Однако этот уровень доступа доступен только для локальных установок Jira (Server или Data Center), где у вас есть прямой доступ к серверу. Если вы работаете с Jira Cloud или создаете автономную интеграцию, то лучше использовать REST API.

Что такое REST API

REST (Representational State Transfer) - это архитектурный стиль, который определяет набор ограничений для создания веб-сервисов. REST API предоставляет набор HTTP-конечных точек, к которым можно обращаться, отправляя запросы с определенными HTTP-методами (GET, POST, PUT, DELETE) для выполнения операций над ресурсами.

REST API Jira следует этой архитектуре, предоставляя исчерпывающий набор конечных точек для взаимодействия практически с каждым аспектом Jira, от задач и проектов до досок Agile и панелей мониторинга. Он возвращает данные в формате JSON и поддерживает различные методы аутентификации для обеспечения безопасного доступа.

Одним из ключевых преимуществ REST API является его независимость от платформы - вы можете вызывать API с любого устройства или приложения, которое может отправлять HTTP-запросы, независимо от используемого языка программирования. Это делает его идеальным выбором для построения интеграций между Jira и другими инструментами или для создания скриптов взаимодействия с Jira из командной строки.

Что можно сделать с помощью REST API Jira?

Возможности практически безграничны. Вот лишь несколько примеров того, чего вы можете достичь с помощью REST API Jira:

• Автоматизация создания задач: Интегрируйте Jira с вашей системой отслеживания ошибок или инструментом поддержки клиентов для автоматического создания задач в Jira при возникновении определенных событий, с указанием всех соответствующих деталей.
• Синхронизация данных между системами: Поддерживайте синхронизацию Jira с другими инструментами в вашем конвейере разработки, такими как системы контроля версий, инструменты CI/CD или тестовые комплексы. API позволяет отражать изменения в Jira в других системах и наоборот.
• Массовые операции: Нужно одновременно обновить большое количество задач? REST API поддерживает массовые операции создания, обновления и удаления, экономя бесчисленные часы ручной работы.
• Пользовательские дашборды и отчеты: Получайте данные из Jira и используйте их для создания пользовательских дашбордов, отчетов или визуализаций данных, адаптированных к конкретным потребностям вашей команды.
• Расширение функциональности Jira: Создавайте кастомные приложения и интеграции, которые расширяют возможности Jira, добавляют новые функции или оптимизируют рабочие процессы, специфичные для вашей организации.
• Миграция данных: Переходите с другой системы отслеживания задач на Jira? Используйте API для программного импорта ваших существующих данных в Jira.
• Резервное копирование и архивация: Настройте скрипты для регулярного резервного копирования ваших данных Jira или архивирования старых проектов и задач.

Это лишь несколько примеров - REST API Jira предоставляет обширный набор конечных точек, которые охватывают практически каждую функцию, доступную в пользовательском интерфейсе Jira. Если вы можете сделать это в Jira, скорее всего, вы можете сделать это и через API.

Ключевые различия между REST API Jira Cloud и Data Center

Хотя REST API Jira предоставляет в основном одинаковые возможности для Jira Cloud, Server и Data Center, есть несколько ключевых различий, о которых следует знать:

• Аутентификация: Jira Cloud использует OAuth 2.0 или API токены для аутентификации, обеспечивая безопасный и стандартизированный метод предоставления доступа к API. С другой стороны, Jira Data Center в основном использует базовую аутентификацию или сессионные cookie.
• Версионирование API: REST API Jira Cloud имеет версии (в настоящее время версия 3), позволяя Atlassian развивать и улучшать API с течением времени, не нарушая существующие интеграции. Однако Jira Data Center не имеет явного версионирования - API привязан к конкретной версии Jira.
• Ограничение скорости: Чтобы обеспечить справедливое использование и поддерживать производительность, Jira Cloud применяет более строгие ограничения скорости для API-запросов по сравнению с Data Center. Интеграции должны разрабатываться с учетом этих ограничений и реализовывать соответствующее регулирование и обработку ошибок.
• Формат URL: URL-адреса конечных точек REST API немного различаются между Cloud и Data Center. Для Jira Cloud базовый URL имеет формат https://your-domain.atlassian.net/rest/api/3/, а для Data Center - https://your-jira-instance.com/rest/api/latest/.

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

Что нужно для работы с REST API Jira?

Чтобы начать работать с REST API Jira, вам понадобится:

• Экземпляр Jira: Это может быть сайт Jira Cloud или локальный экземпляр Jira Server или Data Center. Вам понадобится доступ администратора для настройки и управления вашими интеграциями API.
• Учетные данные для аутентификации: В зависимости от вашего развертывания Jira это может быть токен OAuth 2.0, API-токен или базовые учетные данные для аутентификации (имя пользователя и пароль).
• API-клиент: Для выполнения HTTP-запросов к API вам понадобится API-клиент. Это может быть специальный инструмент для тестирования API, такой как Postman, инструмент командной строки, такой как cURL, или HTTP-библиотека на выбранном вами языке программирования (например, библиотека requests в Python или Fetch API в JavaScript).
• Ссылка на документацию по API Jira: Atlassian предоставляет обширную документацию по REST API Jira с подробным описанием каждой конечной точки, ее параметров, а также примеров запросов и ответов. Держите ее под рукой, пока изучаете API.

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

Как использовать REST API Jira

Давайте пройдемся по практическому примеру использования REST API Jira для создания, получения, обновления и поиска задач. Мы будем использовать Postman для наших примеров, но принципы применимы к любому API-клиенту.

Шаг 1: Создайте учетную запись Jira Cloud

Если у вас еще нет экземпляра Jira для работы, самый простой способ начать - зарегистрироваться для получения бесплатного экземпляра Jira Cloud на https://www.atlassian.com/software/jira. Как только ваш сайт будет настроен, создайте новый проект для работы.

Шаг 2: Сгенерируйте API-токен Jira

Для аутентификации наших API-запросов мы будем использовать API-токен. Вот как его сгенерировать:

1. Войдите в свою учетную запись Atlassian и перейдите на https://id.atlassian.com/manage-profile/security/api-tokens.
2. Нажмите "Create API token", дайте вашему токену описательную метку и нажмите "Create".

3. Скопируйте сгенерированный токен и храните его в безопасном месте. Вы не сможете увидеть его снова после того, как покинете эту страницу.

Шаг 3: Сделайте свой первый API-запрос с помощью Postman

Давайте начнем с получения подробной информации о существующей задаче:

1. Откройте Postman и создайте новый запрос.
2. Установите метод HTTP на GET и введите URL для конечной точки детальной информации о задаче, заменив your-domain на домен вашего сайта Jira, а ISSUE-KEY - на ключ задачи в вашем проекте: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
3. На вкладке "Authorization" выберите "Basic Auth" в качестве типа. Введите адрес электронной почты вашей учетной записи Atlassian в качестве имени пользователя и вставьте ваш API-токен в качестве пароля.
4. Нажмите "Send". Если все настроено правильно, вы должны увидеть ответ в формате JSON с полной информацией об указанной задаче, включая ее поля, комментарии, вложения и многое другое.

Шаг 4: Создайте задачу

Теперь давайте создадим новую задачу через API:

1. В Postman измените метод HTTP на POST и обновите URL на конечную точку создания задачи: https://your-domain.atlassian.net/rest/api/3/issue
2. На вкладке "Headers" добавьте новую пару ключ-значение: "Content-Type" и "application/json". Это сообщает Jira, что мы отправляем данные в формате JSON.

Перейдите на вкладку "Body", выберите переключатель "raw" и введите следующий JSON, заменив значения project.key, issuetype.name, summary и description по мере необходимости:

 json

{
  "fields": {
    "project": {
      "key": "YOUR_PROJECT_KEY"
    },
    "issuetype": {
       "name": "Task"
    },
    "summary": "Issue created via REST API",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "This is a test issue created using the Jira REST API."
            }
          ]
        }
      ]
    }
  }
}

3. Нажмите "Send". Jira ответит со статусом 201 Created и полной информацией о новой созданной задаче.

Шаг 5: Обновите задачу

Для обновления существующей задачи мы используем метод PUT:

1. Измените метод HTTP на PUT и обновите URL, чтобы он указывал на задачу, которую вы хотите обновить: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY

В теле запроса укажите поля, которые вы хотите обновить, например:

 json

{
  "fields": {
    "summary": "Updated summary",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "This issue has been updated via the REST API."
            }
          ]
        }
      ]
    }
  }
}

2. Нажмите "Send". Jira ответит со статусом 204 No Content, указывая на то, что обновление прошло успешно.

Шаг 6: Поиск задач с помощью JQL

Мощные возможности поиска Jira также доступны через REST API с использованием JQL (Jira Query Language):

1. Измените метод HTTP обратно на POST и обновите URL до конечной точки поиска: https://your-domain.atlassian.net/rest/api/3/search

В теле запроса укажите JQL-запрос и любые дополнительные параметры:

 json
Copy
{
  "jql": "project = YOUR_PROJECT_KEY AND status = 'To Do' ORDER BY created DESC",
  "fields": ["summary", "status", "assignee"],
  "maxResults": 10
}

Этот запрос вернет 10 последних созданных задач в статусе "To Do" из указанного проекта, включая только поля summary, status и assignee.

2. Нажмите "Send". Jira ответит JSON-массивом задач, соответствующих вашим критериям поиска.

Эти примеры лишь слегка затрагивают то, что возможно с REST API Jira. По мере того, как вы будете больше знакомиться с доступными конечными точками и параметрами, вы сможете создавать все более сложные и мощные интеграции.

Как автоматизировать создание и обновление задач в Jira с помощью Нодуль

Одним из самых мощных применений REST API Jira является автоматизация создания и обновления задач. С помощью Нодуля вы можете настроить сложные рабочие процессы, которые автоматически создают и обновляют задачи в Jira на основе данных из внешних источников или специфических триггеров. Это гарантирует, что информация в вашей системе управления проектами остается актуальной и своевременной, повышая эффективность команды.

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

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

• Простота использования: Нодуль упрощает процесс использования API Jira, облегчая нетехническим пользователям автоматизацию задач управления проектами.
• Гибкие цены: Пользователи могут выбирать между различными планами Нодуля с разной стоимостью и функциями, наиболее подходящими для их потребностей.
• Комплексные решения: Интеграция Нодуля с Jira предоставляет доступ к широкому спектру возможностей управления проектами и отслеживания задач.
• Индивидуальная настройка: Пользователи могут настраивать интеграцию Jira в соответствии со своими конкретными потребностями, позволяя создавать индивидуальные решения для автоматизации, соответствующие бизнес-целям.

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

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

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

Это лишь один пример того, как Нодуль может преобразовать ваш подход к использованию API Jira с помощью мощной автоматизации. На самом деле возможности платформы практически безграничны - вы можете создавать любые сценарии автоматизации, необходимые для повышения эффективности вашего бизнеса. Будь то автоматическое распределение задач, отправка уведомлений, отслеживание ключевых показателей производительности или любые другие задачи - Нодуль предоставляет инструменты для их воплощения в жизнь.

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

Пагинация, раскрытие и сортировка в REST API Jira

Когда вы начнете работать с большими наборами данных в Jira, вам нужно будет знать, как REST API обрабатывает пагинацию, раскрытие вложенных ресурсов и сортировку результатов.

Раскрытие

Многие ресурсы Jira содержат ссылки на другие вложенные ресурсы. Например, задача (Issue) содержит ссылки на свой проект (Project), тип задачи (Issuetype), создателя (Creator), репортера (Reporter), исполнителя (Assignee), комментарии (Comments), вложения (Attachments) и многое другое. По умолчанию эти вложенные ресурсы возвращаются в виде заглушек, содержащих только несколько базовых полей и ссылку на сам полный ресурс.

Если вам нужны полные данные вложенного ресурса, вы можете использовать параметр запроса expand, чтобы запросить включение полного ресурса в ответ. Например, чтобы включить полные данные проекта и исполнителя задачи:

GET .../rest/api/3/issue/ISSUE-KEY?expand=project,assignee

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

Пагинация

Запросы, которые потенциально могут вернуть большое количество результатов (например, поиск JQL), по умолчанию разбиваются на страницы. API будет возвращать максимальное количество результатов на страницу (по умолчанию 50, но настраивается до 100) вместе со ссылками на следующую и предыдущую страницы.

Вы можете управлять пагинацией с помощью параметров startAt и maxResults:

• startAt: Индекс первого возвращаемого результата (начиная с 0)
• maxResults: Максимальное количество результатов, возвращаемых на страницу

Например, чтобы получить вторую страницу результатов с размером страницы 20:

GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&startAt=20&maxResults=20

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

Сортировка

Вы можете контролировать порядок результатов с помощью параметра orderBy, который принимает список полей для сортировки, разделенных запятыми. Каждое поле может быть с префиксом -, указывающим на сортировку в обратном порядке.

Например, чтобы отсортировать задачи по дате создания в обратном порядке, а затем по приоритету в прямом порядке:

GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&orderBy=-created,priority

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

Примеры использования API Jira

Вот еще пара более продвинутых примеров, демонстрирующих мощь REST API Jira для массовых операций.

Массовое создание/обновление задач из CSV

Предположим, у вас есть CSV-файл, содержащий данные для нескольких задач, которые вы хотите создать или обновить в Jira. Вы можете использовать такой инструмент, как Postman, для автоматизации этого процесса:

1. В Postman создайте новый запрос для конечной точки создания или обновления задачи.

На вкладке Body выберите переключатель "raw" и введите шаблон для данных вашей задачи, используя переменные для полей, которые будут браться из вашего CSV:

{
  "fields": {
    "project": {"key": "{{project_key}}"},
    "issuetype": {"name": "{{issue_type}}"},
    "summary": "{{summary}}",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "{{description}}"
            }
          ]
        }
      ]
    },
    "assignee": {"name": "{{assignee}}"},
    "priority": {"name": "{{priority}}"}
  }
}

2. Перейдите на вкладку "Pre-request Script" и добавьте код для чтения вашего CSV-файла и установки соответствующих переменных:

const csvFile = pm.iterationData.readCSV();
pm.variables.set('project_key', csvFile[0]);
pm.variables.set('issue_type', csvFile[1]);
pm.variables.set('summary', csvFile[2]);
pm.variables.set('description', csvFile[3]);
pm.variables.set('assignee', csvFile[4]);
pm.variables.set('priority', csvFile[5]);

1. В окне "Runner" выберите ваш CSV-файл в качестве файла данных и запустите выполнение. Postman создаст новый запрос для каждой строки в вашем CSV, подставляя переменные из файла.

Это мощная техника для массового импорта данных в Jira из внешних источников.

Массовое создание/обновление задач из JSON

Если ваши исходные данные уже в формате JSON, вы можете использовать конечную точку массового создания/обновления для обработки нескольких задач в одном запросе:

POST https://your-domain.atlassian.net/rest/api/3/issue/bulk

Тело запроса должно содержать массив объектов создания/обновления задач, каждый из которых следует тому же формату, что и запрос на создание/обновление одной задачи:

{
  "issueUpdates": [
    {
      "fields": {
        "project": {"key": "PROJ1"},
        "issuetype": {"name": "Task"},
        "summary": "Issue 1",
        "description": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "First issue created via bulk update"
                }
              ]
            }
          ]
        }
      }
    },
    {
      "fields": {
        "project": {"key": "PROJ2"},
        "issuetype": {"name": "Bug"},
        "summary": "Issue 2",
        "description": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Second issue created via bulk update"
                }
              ]
            }
          ]
        },
        "priority": {"name": "High"},
        "labels": ["bulk-import", "api-test"]
      }
    }
  ]
}

Это создаст две задачи в одном запросе - Task в проекте PROJ1 и Bug в проекте PROJ2. Вы можете включить до 50 задач в один массовый запрос.

Конечная точка массовых операций также полезна для выполнения массовых переходов, обновлений и удалений. Например, чтобы перевести несколько задач в статус "Done":

{
  "transition": {
    "id": "31"
  },
  "issues": [
    {"key": "ISSUE-1"},
    {"key": "ISSUE-2"},
    {"key": "ISSUE-3"}
  ]
}

Это предполагает, что "31" - это ID вашего перехода "Done" - вы можете найти доступные переходы для типа задачи через конечную точку /rest/api/3/issue/{issueIdOrKey}/transitions.

Вывод

REST API Jira - это невероятно мощный инструмент для интеграции Jira с другими системами, автоматизации задач и расширения возможностей Jira. В этом руководстве мы рассмотрели основы API, включая:

• Различие между Java API и REST API, и когда использовать каждый из них
• Ключевые различия между API для Cloud и Server/Data Center
• Как аутентифицироваться в API с помощью API-токенов или базовой аутентификации
• Выполнение ваших первых API-запросов с помощью Postman
• Создание, получение, обновление и поиск задач
• Обработка пагинации, раскрытия и сортировки результатов
• Продвинутые случаи использования, такие как массовое создание/обновление из данных CSV и JSON

Однако мы лишь слегка коснулись поверхности. REST API Jira предоставляет конечные точки для работы практически с каждым аспектом Jira, от проектов и досок до пользователей и разрешений. По мере создания ваших интеграций обязательно обращайтесь к официальной документации Atlassian для получения самой актуальной и полной информации.

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