O que é Jira REST API: como aproveitar a REST API e proteger a chave da API do Jira
Utilizando a API REST do Jira: Um Guia Abrangente
O Jira, a versátil plataforma de gerenciamento de projetos e rastreamento de problemas da Atlassian, se tornou uma ferramenta indispensável para inúmeras equipes de desenvolvimento no mundo todo. Embora sua interface amigável facilite o gerenciamento de projetos e o rastreamento de problemas, o verdadeiro poder do Jira está em suas extensas opções de personalização e recursos de integração. No centro disso está a API REST do Jira, que abre um mundo de possibilidades para automatizar tarefas, criar aplicativos personalizados e integrar perfeitamente o Jira com outras ferramentas em seu ecossistema de desenvolvimento. Neste guia abrangente, vamos nos aprofundar na API REST do Jira, explorar seus recursos e apresentar exemplos práticos para ajudar você a começar.
Key Takeaways: A API REST do Jira é uma ferramenta versátil para automatizar tarefas, criar aplicativos personalizados e integrar o Jira com outras ferramentas de desenvolvimento nas versões Cloud e Server/Data Center. Ela oferece uma ampla gama de recursos, incluindo gerenciamento de problemas, operações em massa e relatórios personalizados, com suporte para recursos avançados como paginação e expansão de dados. Embora existam algumas diferenças entre as versões, a funcionalidade principal da API permanece consistente, permitindo que as equipes personalizem o Jira de forma eficiente para suas necessidades específicas e o integrem perfeitamente com seu ecossistema de desenvolvimento.
Você pode experimentar o Jira sem usar API no Latenode
O que é a API do Jira?
Em sua essência, uma API (Application Programming Interface) é um conjunto de protocolos e ferramentas que especificam como os componentes de software devem interagir. No contexto do Jira, a API permite que aplicativos externos interajam com o Jira programaticamente, permitindo a recuperação e manipulação de dados, bem como a execução de ações dentro do Jira. O Jira fornece dois tipos de APIs:
O que é API Java
A API Java do Jira é uma ferramenta poderosa para desenvolvedores que criam aplicativos ou plugins Jira personalizados. Ela fornece acesso direto aos objetos e métodos Java subjacentes do servidor Jira, permitindo integração e personalização profundas. No entanto, esse nível de acesso só está disponível para instalações Jira no local (servidor ou data center) onde você tem acesso direto ao servidor. Se você estiver trabalhando com o Jira Cloud ou criando uma integração autônoma, a API REST é o caminho a seguir.
O que é REST API
REST (Representational State Transfer) é um estilo arquitetônico que define um conjunto de restrições para criar serviços web. Uma API REST expõe um conjunto de endpoints HTTP que podem ser acessados enviando solicitações com métodos HTTP específicos (GET, POST, PUT, DELETE) para executar operações em recursos.
A API REST do Jira segue essa arquitetura, fornecendo um conjunto abrangente de endpoints para interagir com quase todos os aspectos do Jira, de problemas e projetos a painéis e painéis ágeis. Ela retorna dados no formato JSON e suporta uma variedade de métodos de autenticação para garantir acesso seguro.
Uma das principais vantagens da REST API é sua independência de plataforma - você pode chamar a API de qualquer dispositivo ou aplicativo que possa fazer solicitações HTTP, independentemente da linguagem de programação usada. Isso a torna a escolha ideal para construir integrações entre o Jira e outras ferramentas, ou para criar scripts de interações com o Jira a partir da linha de comando.
O que você pode fazer com a API REST do Jira?
As possibilidades são quase infinitas. Aqui estão apenas alguns exemplos do que você pode conseguir com a Jira REST API:
- Automatizar a criação de problemas: Integre o Jira ao seu sistema de rastreamento de erros ou ferramenta de suporte ao cliente para criar problemas automaticamente no Jira quando determinados eventos ocorrerem, incluindo todos os detalhes relevantes.
- Sincronizar dados entre sistemas: Mantenha o Jira sincronizado com outras ferramentas no seu pipeline de desenvolvimento, como sistemas de controle de origem, ferramentas de CI/CD ou suítes de gerenciamento de testes. A API permite que você reflita alterações no Jira para outros sistemas e vice-versa.
- Operações em Massa: Precisa atualizar um grande número de problemas de uma vez? A REST API suporta operações de criação, atualização e exclusão em massa, economizando inúmeras horas de trabalho manual.
- Painéis e relatórios personalizados: Recupere dados do Jira e use-os para criar painéis, relatórios ou visualizações de dados personalizados, adaptados às necessidades específicas da sua equipe.
- Amplie a funcionalidade do Jira: Crie aplicativos e integrações personalizados que estendam os recursos do Jira, adicionem novos recursos ou simplifiquem fluxos de trabalho específicos para sua organização.
- Migrar Dados: Mudando de outro sistema de rastreamento de problemas para o Jira? Use a API para importar programaticamente seus dados existentes para o Jira.
- Backup e arquivo: Configure scripts para fazer backup regularmente dos seus dados do Jira ou arquivar projetos e problemas antigos.
Esses são apenas alguns exemplos - a API REST do Jira fornece um conjunto extenso de endpoints que cobrem quase todos os recursos e funções disponíveis na interface de usuário do Jira. Se você consegue fazer isso no Jira, é provável que consiga fazer isso por meio da API.
Principais diferenças entre a API REST do Jira Cloud e a API REST do Data Center
Embora a API REST do Jira forneça basicamente os mesmos recursos no Jira Cloud, Server e Data Center, há algumas diferenças importantes que você deve conhecer:
- Autenticação: O Jira Cloud usa OAuth 2.0 ou tokens de API para autenticação, fornecendo um método seguro e baseado em padrões para conceder acesso à API. O Jira Data Center, por outro lado, usa principalmente autenticação básica ou cookies de sessão.
- Controle de versão de API: A API REST do Jira Cloud é versionada (atualmente na versão 3), permitindo que a Atlassian evolua e melhore a API ao longo do tempo sem quebrar as integrações existentes. O Jira Data Center, no entanto, não tem versionamento explícito - a API é vinculada à versão específica do Jira.
- Limitação de taxa: Para garantir o uso justo e manter o desempenho, o Jira Cloud impõe limites de taxa mais rigorosos em solicitações de API em comparação ao Data Center. As integrações precisam ser projetadas com esses limites em mente e implementar limitação e tratamento de erros apropriados.
- Formato URLOs URLs dos endpoints da API REST diferem ligeiramente entre o Jira Cloud e o Data Center. Para o Jira Cloud, o URL base tem o formato https://your-domain.atlassian.net/rest/api/3/, enquanto para o Data Center é https://your-jira-instance.com/rest/api/latest/.
Apesar dessas diferenças, os conceitos principais e os padrões de uso da API REST permanecem basicamente os mesmos em todas as implantações. As habilidades e o conhecimento que você ganha trabalhando com uma versão da API serão facilmente transferíveis para outras.
O que você precisa para trabalhar com a API REST do Jira?
Para começar a usar a API REST do Jira, você precisará:
- Uma instância do Jira: Este pode ser um site do Jira Cloud ou uma instância do Jira Server ou Data Center auto-hospedada. Você precisará de acesso de administrador para configurar e gerenciar suas integrações de API.
- Credenciais de Autenticação: Dependendo da sua implantação do Jira, isso pode ser um token OAuth 2.0, um token de API ou credenciais de autenticação básicas (nome de usuário e senha).
- Cliente API: Para fazer solicitações HTTP para a API, você precisará de um cliente de API. Pode ser uma ferramenta de teste de API dedicada como o Postman, uma ferramenta de linha de comando como o cURL ou a biblioteca HTTP na linguagem de programação de sua escolha (por exemplo, a biblioteca de solicitações do Python ou a API fetch do JavaScript).
- Referência da documentação da API do Jira: A Atlassian fornece documentação extensa para a API REST do Jira, detalhando cada endpoint, seus parâmetros e solicitações e respostas de exemplo. Mantenha isso à mão enquanto explora a API.
Com esses elementos em vigor, você está pronto para começar a fazer suas primeiras solicitações de API.
Como usar a API REST do Jira
Vamos percorrer um exemplo prático de uso da API REST do Jira para criar, recuperar, atualizar e pesquisar problemas. Usaremos o Postman para nossos exemplos, mas os princípios se aplicam a qualquer cliente de API.
Etapa 1: Crie uma conta no Jira Cloud
Se você ainda não tem uma instância do Jira para trabalhar, a maneira mais fácil de começar é se inscrever para uma instância gratuita do Jira Cloud em https://www.atlassian.com/software/jira. Depois que seu site estiver configurado, crie um novo projeto para trabalhar.
Etapa 2: gerar um token da API do Jira
Para autenticar nossas solicitações de API, usaremos um token de API. Veja como gerar um:
- Entre na sua conta Atlassian e navegue até https://id.atlassian.com/manage-profile/security/api-tokens.
- Clique em "Criar token de API", dê um rótulo descritivo ao seu token e clique em "Criar".
- Copie o token gerado e armazene-o com segurança. Você não poderá visualizá-lo novamente após sair desta página.
Etapa 3: faça sua primeira solicitação de API com o Postman
Vamos começar recuperando os detalhes de um problema existente:
- Abra o Postman e crie uma nova solicitação.
- Defina o método HTTP como GET e insira a URL do endpoint de detalhes da tarefa, substituindo seu-domínio pelo domínio do seu site Jira e CHAVE-DA-TAREFA pela chave de uma tarefa em seu projeto: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
- Na aba "Authorization", selecione "Basic Auth" como o tipo. Insira o endereço de e-mail da sua conta Atlassian como nome de usuário e cole seu token de API como senha.
- Clique em "Enviar". Se tudo estiver configurado corretamente, você deverá ver uma resposta JSON com todos os detalhes do problema especificado, incluindo seus campos, comentários, anexos e mais.
Etapa 4: Crie um problema
Agora vamos criar um novo problema via API:
- No Postman, altere o método HTTP para POST e atualize a URL para o endpoint de criação de problemas: https://your-domain.atlassian.net/rest/api/3/issue
- Na aba "Headers", adicione um novo par de chave-valor: "Content-Type" e "application/json". Isso informa ao Jira que estamos enviando um payload JSON.
Mude para a aba "Corpo", selecione o botão de opção "bruto" e insira o seguinte JSON, substituindo os valores project.key, issuetype.name, summary e description conforme apropriado:
json
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {
<span class="hljs-string">"key"</span>: <span class="hljs-string">"YOUR_PROJECT_KEY"</span>
},
<span class="hljs-string">"issuetype"</span>: {
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Task"</span>
},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Issue created via REST API"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"This is a test issue created using the Jira REST API."</span>
}
]
}
]
}
}
}
3. Clique em "Enviar". O Jira responderá com o status 201 Criado e os detalhes completos do problema recém-criado.
Etapa 5: Atualizar um problema
Para atualizar um problema existente, usamos o método PUT:
- Altere o método HTTP para PUT e atualize a URL para apontar para a issue que você deseja atualizar: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
No corpo da solicitação, inclua os campos que deseja atualizar, por exemplo:
json
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Updated summary"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"This issue has been updated via the REST API."</span>
}
]
}
]
}
}
}
2. Clique em "Enviar". O Jira responderá com o status 204 Sem conteúdo para indicar que a atualização foi bem-sucedida.
Etapa 6: Pesquisar problemas usando JQL
Os poderosos recursos de pesquisa do Jira também podem ser acessados por meio da API REST usando JQL (Jira Query Language):
- Altere o método HTTP de volta para POST e atualize o URL para o endpoint de pesquisa: https://your-domain.atlassian.net/rest/api/3/search
No corpo da solicitação, inclua uma consulta JQL e quaisquer parâmetros adicionais:
<span class="hljs-type">json</span>
<span class="hljs-keyword">Copy</span>
{
"jql": "project = YOUR_PROJECT_KEY AND status = 'To Do' ORDER BY created DESC",
"fields": ["summary", "status", "assignee"],
"maxResults": <span class="hljs-number">10</span>
}
Esta consulta retornará os 10 problemas criados mais recentemente no status "A fazer" do projeto especificado, incluindo apenas os campos de resumo, status e responsável.
- Clique em "Enviar". O Jira responderá com uma matriz JSON de problemas que correspondem aos seus critérios de pesquisa.
Esses exemplos apenas arranham a superfície do que é possível com a API REST do Jira. À medida que você se familiariza mais com os endpoints e parâmetros disponíveis, você será capaz de construir integrações cada vez mais complexas e poderosas.
Você pode automatizar o Jira sem usar API no Latenode
Como automatizar a criação e atualizações de problemas no Jira usando o Latenode
Uma das aplicações mais poderosas da API REST do Jira é a criação de tarefas e automação de atualizações. Com o Latenode, você pode configurar fluxos de trabalho sofisticados que criam e atualizam tarefas automaticamente no Jira com base em dados de fontes externas ou gatilhos específicos. Isso garante que as informações no seu sistema de gerenciamento de projetos permaneçam atualizadas e oportunas, aumentando a eficiência da equipe.
Por exemplo, você pode criar um fluxo de trabalho que cria automaticamente uma nova tarefa no Jira quando uma mensagem de erro é recebida de um sistema de monitoramento, preenchendo todos os campos necessários e atribuindo a tarefa ao desenvolvedor apropriado. Conforme as atualizações chegam, a tarefa pode ser atualizada automaticamente e, quando o problema é resolvido, ela pode ser fechada. Essa abordagem simplificada não apenas melhora o rastreamento de problemas, mas também economiza tempo para sua equipe, permitindo que eles se concentrem na resolução de problemas em vez de administrá-los.
Você pode aprender mais sobre esse script e a integração com o Latenode neste artigo. A integração com o Latenode oferece alguns benefícios importantes:
- Facilidade de uso O Latenode simplifica o processo de uso da API do Jira, facilitando para usuários não técnicos automatizar tarefas de gerenciamento de projetos.
- Preços flexíveis Os usuários podem escolher entre diferentes planos do Latenode, com custos e recursos variados, para melhor atender às suas necessidades.
- Soluções Completas A integração do Latenode com o Jira fornece acesso a uma ampla gama de recursos de gerenciamento de projetos e rastreamento de problemas.
- Customização Os usuários podem personalizar as integrações do Jira para atender às suas necessidades específicas, permitindo soluções de automação personalizadas e alinhadas às metas de negócios.
Imagine cada e-mail importante de um cliente se transformando automaticamente em uma tarefa no Jira. Com o Latenode, isso se torna realidade. Nossa plataforma garante a criação de uma nova tarefa no projeto certo com campos preenchidos com base no conteúdo do e-mail, garantindo que nenhuma solicitação importante seja perdida.
Veja um exemplo de como um fluxo de trabalho do Latenode automatiza a criação e as atualizações de tarefas do Jira com base em dados de e-mail recebidos de uma fonte externa.
Esta imagem mostraria uma representação visual do fluxo de trabalho na interface do Latenode, com nós conectados representando cada etapa do processo, desde o recebimento de e-mail até a criação de tarefas do Jira.
Este é apenas um exemplo de como o Latenode pode transformar sua abordagem para usar a API do Jira com automação poderosa. Na verdade, os recursos da plataforma são virtualmente ilimitados - você pode criar quaisquer cenários de automação necessários para melhorar a eficiência do seu negócio. Seja distribuição automática de tarefas, envio de notificações, rastreamento de indicadores-chave de desempenho ou quaisquer outras tarefas - o Latenode fornece as ferramentas para dar vida a elas.
Ao aproveitar o criador de fluxo de trabalho visual do Latenode e a integração perfeita com a API REST do Jira, você pode facilmente projetar e implementar cenários de automação complexos, aumentando a eficiência do gerenciamento de projetos e acelerando os fluxos de trabalho da sua equipe.
Se precisar de ajuda ou conselhos sobre como criar seu próprio script ou se quiser replicar este, entre em contato nossa comunidade no Discord, onde estão localizados os especialistas em automação de baixo código.
Paginação, expansão e ordenação da API REST do Jira
Ao começar a trabalhar com conjuntos de dados maiores no Jira, você precisará estar ciente de como a API REST lida com paginação, expansão de recursos aninhados e ordenação de resultados.
Expansão
Muitos recursos do Jira contêm referências a outros recursos aninhados. Por exemplo, um Issue contém referências ao seu Project, Issuetype, Creator, Reporter, Assignee, Comments, Attachments e muito mais. Por padrão, esses recursos aninhados são retornados como stubs, contendo apenas alguns campos básicos e um self link para o recurso completo.
Se precisar dos detalhes completos de um recurso aninhado, você pode usar o parâmetro de consulta expand para solicitar que o Jira inclua o recurso completo na resposta. Por exemplo, para incluir os detalhes completos do projeto e do cessionário de um problema:
<span class="hljs-built_in">GET</span> <span class="hljs-built_in">..</span>./rest/api/3/issue/ISSUE-KEY?<span class="hljs-attribute">expand</span>=project,assignee
Você pode expandir vários recursos separando-os por vírgulas. Esteja ciente de que expansões podem aumentar significativamente o tamanho do payload de resposta, então use-as criteriosamente.
Paginação
Solicitações que poderiam potencialmente retornar um grande número de resultados (como pesquisas JQL) são paginadas por padrão. A API retornará um número máximo de resultados por página (padrão para 50, mas personalizável até 100) junto com links para as páginas seguintes e anteriores.
Você pode controlar a paginação usando os parâmetros startAt e maxResults:
- startAt: O índice do primeiro resultado a retornar (baseado em 0)
- maxResults: O número máximo de resultados a serem retornados por página
Por exemplo, para recuperar a segunda página de resultados com um tamanho de página de 20:
<span class="hljs-built_in">GET</span> <span class="hljs-built_in">..</span>./rest/api/3/search?<span class="hljs-attribute">jql</span>=project=YOUR_PROJECT_KEY&startAt=20&maxResults=20
Seu aplicativo precisará lidar com várias solicitações para recuperar todas as páginas de resultados.
Encomendar
Você pode controlar a ordem dos resultados usando o parâmetro orderBy, que aceita uma lista separada por vírgulas de campos para ordenar. Cada campo pode ser prefixado com um - para indicar ordem decrescente.
Por exemplo, para ordenar os problemas por data de criação em ordem decrescente e depois por prioridade em ordem crescente:
OBTER .../rest/api/3/search?jql=project=SUA_CHAVE_DE_PROJETO&orderBy=-criado,prioridade
Nem todos os campos suportam ordenação - consulte a documentação do endpoint específico para ver o que está disponível.
Exemplos de uso da API do Jira
Aqui estão mais alguns exemplos avançados que demonstram o poder da API REST do Jira para operações em massa.
Criação/atualização em massa de problemas de CSV
Suponha que você tenha um arquivo CSV contendo dados para vários problemas que você deseja criar ou atualizar no Jira. Você pode usar uma ferramenta como o Postman para automatizar esse processo:
- No Postman, crie uma nova solicitação para o endpoint de criação ou atualização do problema.
Na aba Corpo, selecione o botão de opção "bruto" e insira um modelo para os dados do seu problema, usando variáveis para os campos que virão do seu CSV:
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {<span class="hljs-string">"key"</span>: <span class="hljs-string">"{{project_key}}"</span>},
<span class="hljs-string">"issuetype"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"{{issue_type}}"</span>},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"{{summary}}"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"{{description}}"</span>
}
]
}
]
},
<span class="hljs-string">"assignee"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"{{assignee}}"</span>},
<span class="hljs-string">"priority"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"{{priority}}"</span>}
}
}
2. Mude para a aba "Script de pré-solicitação" e adicione o código para ler seu arquivo CSV e defina as variáveis correspondentes:
const csvFile = pm.iterationData.readCSV();
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'project_key'</span>, csvFile[0]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'issue_type'</span>, csvFile[1]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'summary'</span>, csvFile[2]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'description'</span>, csvFile[3]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'assignee'</span>, csvFile[4]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'priority'</span>, csvFile[5]);
3. Na janela "Runner", selecione seu arquivo CSV como o arquivo de dados e inicie a execução. O Postman criará uma nova solicitação para cada linha em seu CSV, substituindo as variáveis do arquivo.
Esta é uma técnica poderosa para importar dados em massa para o Jira de fontes externas.
Criação/atualização em massa de problemas do JSON
Se seus dados de origem já estiverem no formato JSON, você poderá usar o endpoint de criação/atualização em massa para processar vários problemas em uma única solicitação:
POST https://your-domain.atlassian.net/rest/api/3/issue/bulk
O corpo da solicitação deve conter uma matriz de objetos de criação/atualização de problemas, cada um seguindo o mesmo formato de uma única solicitação de criação/atualização de problemas:
{
<span class="hljs-string">"issueUpdates"</span>: [
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {<span class="hljs-string">"key"</span>: <span class="hljs-string">"PROJ1"</span>},
<span class="hljs-string">"issuetype"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"Task"</span>},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Issue 1"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"First issue created via bulk update"</span>
}
]
}
]
}
}
},
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {<span class="hljs-string">"key"</span>: <span class="hljs-string">"PROJ2"</span>},
<span class="hljs-string">"issuetype"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"Bug"</span>},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Issue 2"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"Second issue created via bulk update"</span>
}
]
}
]
},
<span class="hljs-string">"priority"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"High"</span>},
<span class="hljs-string">"labels"</span>: [<span class="hljs-string">"bulk-import"</span>, <span class="hljs-string">"api-test"</span>]
}
}
]
}
Isso criará dois problemas em uma solicitação - uma Tarefa no projeto PROJ1 e um Bug no projeto PROJ2. Você pode incluir até 50 problemas em uma única solicitação em massa.
O endpoint em massa também é útil para executar transições, atualizações e exclusões em massa. Por exemplo, para fazer a transição de vários problemas para o status "Concluído":
{
"<span class="hljs-attribute">transition</span>": {
"id": <span class="hljs-string">"31"</span>
},
"issues": [
{"key": <span class="hljs-string">"ISSUE-1"</span>},
{"key": <span class="hljs-string">"ISSUE-2"</span>},
{"key": <span class="hljs-string">"ISSUE-3"</span>}
]
}
Isso pressupõe que "31" seja o ID da sua transição "Concluída" - você pode encontrar as transições disponíveis para um tipo de problema por meio do endpoint /rest/api/3/issue/{issueIdOrKey}/transitions.
Resumo
A API REST do Jira é uma ferramenta imensamente poderosa para integrar o Jira com outros sistemas, automatizar tarefas e estender os recursos do Jira. Neste guia, cobrimos os fundamentos da API, incluindo:
- A diferença entre as APIs Java e REST e quando usar cada uma
- Principais diferenças entre as APIs de nuvem e de servidor/data center
- Como autenticar na API usando tokens de API ou autenticação básica
- Fazendo suas primeiras solicitações de API usando o Postman
- Criação, recuperação, atualização e busca de problemas
- Manipulando paginação, expansão e ordenação de resultados
- Casos de uso avançados, como criação/atualização em massa de dados CSV e JSON
No entanto, mal arranhamos a superfície. A API REST do Jira fornece endpoints para trabalhar com quase todos os aspectos do Jira, de projetos e quadros a usuários e permissões. Conforme você constrói suas integrações, certifique-se de consultar a documentação oficial do Atlassian para obter as informações mais atualizadas e abrangentes.
Com a API REST do Jira no seu kit de ferramentas, as possibilidades do que você pode fazer com o Jira são quase infinitas. Não importa se você está criando um painel de relatórios personalizado, sincronizando dados com outro sistema ou automatizando fluxos de trabalho complexos, a API fornece a flexibilidade e o poder necessários para fazer isso acontecer.
Você pode experimentar o Jira sem usar API no Latenode
Perguntas frequentes
Quais métodos de autenticação são suportados pela API REST do Jira?
O Jira Cloud oferece suporte a OAuth 2.0 e tokens de API para autenticação. Para OAuth, você precisará registrar seu aplicativo no console do desenvolvedor da Atlassian para obter um ID de cliente e segredo. Os tokens de API são uma opção mais simples para scripts e integrações pessoais. O Jira Server e o Data Center oferecem suporte a Basic Auth (nome de usuário e senha) e autenticação baseada em sessão usando cookies.
A API REST do Jira é diferente entre o Jira Cloud e o Jira Data Center?
Embora os principais endpoints e funcionalidades sejam em grande parte os mesmos, existem algumas diferenças importantes:
- A URL base da API é diferente - Cloud usa https://your-domain.atlassian.net/rest/api/3/, enquanto o servidor/data center usa https://your-jira-instance.com/rest/api/latest/.
- A nuvem impõe limites de taxa mais rígidos e exige autenticação para todas as solicitações, enquanto o servidor/data center tem padrões mais flexíveis.
- Alguns recursos avançados, como as APIs Agile e Service Desk, têm diferenças nos endpoints disponíveis e nos formatos de solicitação/resposta entre a Nuvem e o Servidor/Data Center.
Sempre consulte a documentação específica para sua implantação do Jira para garantir que você esteja usando os URLs e parâmetros corretos.
Como lidar com a limitação de taxa de API?
O Jira Cloud aplica limites de taxa para garantir a estabilidade e o desempenho do serviço. Se você exceder o limite de taxa, receberá uma resposta 429 Too Many Requests.
Para evitar atingir limites de taxa:
- Armazene dados em cache sempre que possível para evitar solicitações repetitivas.
- Use a paginação para recuperar grandes conjuntos de resultados em várias solicitações em vez de tentar recuperar tudo de uma vez.
- Implemente o backoff exponencial no código do seu cliente para aumentar progressivamente o atraso entre as tentativas quando um limite de taxa for encontrado.
- Se você tiver uma necessidade legítima de um limite de taxa mais alto, entre em contato com o suporte da Atlassian para discutir suas opções.
As implantações de servidor e data center têm a limitação de taxa desabilitada por padrão, mas os administradores podem optar por habilitar e configurar limites de taxa, se necessário.
Posso usar a API REST do Jira para servidor/data center?
Sim, o Jira Server e o Data Center têm uma REST API que é muito similar à jira Cloud API. As principais diferenças são:
- A URL base usa /rest/api/latest/ em vez de /rest/api/3/.
- Alguns endpoints podem ter parâmetros ou formatos de resposta ligeiramente diferentes.
- A autenticação normalmente é feita por meio de autenticação básica ou cookies de sessão, em vez de tokens OAuth ou API.
Consulte a documentação da REST API específica do servidor/data center para obter as informações mais precisas para sua versão do Jira.
A API REST do Jira é uma maneira poderosa e flexível de integrar o Jira ao seu fluxo de trabalho de desenvolvimento. Não importa se você está trabalhando na nuvem ou gerenciando seu próprio servidor, a API fornece as ferramentas necessárias para automatizar, personalizar e estender o Jira para atender às necessidades exclusivas da sua equipe. Com um pouco de exploração e experimentação, você poderá desbloquear todo o potencial do Jira e levar seu gerenciamento de projetos para o próximo nível.
