Noções básicas sobre API

O objetivo da API do Adobe Workfront é simplificar a criação de integrações com o Workfront, introduzindo uma arquitetura REST-ful que opera via HTTP. Este documento supõe que você esteja familiarizado com as respostas REST e JSON e descreve a abordagem adotada pela API do Workfront.

Uma familiaridade com o esquema do Workfront ajudará você a entender as relações de banco de dados que podem ser usadas para obter dados do Workfront para fins de integração.

Limites e diretrizes

Para garantir um desempenho consistente do sistema sob demanda do Workfront, cada cliente é limitado a 10 threads de API simultâneos. O ambiente de sandbox tem o mesmo limite em vigor, permitindo que os clientes e parceiros testem com precisão as chamadas de API antes de lançar o código para produção.

Para ambientes de produção, pré-visualização e teste de unidades, as solicitações de usuários finais têm um comprimento máximo de URI de 8892 bytes, pois estão sendo roteadas por meio do Workfront CDN (Akamai). Esse limite se aplica somente aos URIs roteados por meio da CDN.

Isenção de responsabilidade

Qualquer uso da API deve ser testado no ambiente beta do Workfront antes de ser executado no ambiente de produção. Se qualquer cliente usar a API para um processo que a Workfront considere razoavelmente oneroso para o software sob demanda (ou seja, o processo causa um efeito materialmente negativo no desempenho do software para outros clientes), a Workfront se reserva o direito de solicitar que o cliente descontinue esse processo. Se o cliente não estiver em conformidade e o problema persistir, a Workfront se reserva o direito de encerrar o processo.

URL da API Workfront

Para obter informações sobre o URL que você usará para chamar a API do Workfront, consulte Formato de domínio para chamadas de API do Adobe Workfront.

Noções básicas de REST

Esta seção fornece uma introdução de alto nível sobre como interagir com a API REST do Workfront para os seguintes princípios REST:

URI do objeto

Cada objeto no sistema recebe um URI exclusivo que consiste no tipo de objeto e na ID. Os exemplos a seguir mostram URIs que descrevem três objetos únicos:

/attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
/attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d1
/attask/api/v15.0/issue/4c78821c0000d6fa8d5e52f07a1d54d2

O tipo de objeto não diferencia maiúsculas de minúsculas e pode ser o ObjCode abreviado (como proj) ou o nome de objeto alternativo (projeto).

Para obter uma lista de ObjCodes válidos, consulte  API Explorer.

Operações

Os objetos são manipulados enviando uma solicitação HTTP para seu URI exclusivo. A operação a ser executada é especificada pelo método HTTP.

Os métodos HTTP padrão correspondem às seguintes operações:

Para contornar deficiências do cliente ou limites de comprimento do protocolo, o parâmetro do método pode ser usado para substituir o comportamento HTTP. Por exemplo, uma operação GET pode ser implementada publicando o seguinte URI:

GET /attask/api/v15.0/project?id=4c78...54d0&method=get
GET /attask/api/v15.0/project/4c78...54d0?method=get

Resposta

Cada solicitação recebe uma resposta no formato JSON. A resposta tem um atributo de dados se a solicitação tiver sido bem-sucedida ou um atributo de erro se houver um problema. Por exemplo, a solicitação

GET /attask/api/v15.0/proj/4c7c08b20000002de5ca1ebc19edf2d5

retorna uma resposta JSON semelhante ao seguinte:

{
    "data": [
        {
            "percentComplete": 0,
            "status": "CUR",
            "priority": 2,
            "name": "Brand New Project",
            "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
        } 
    ] 
}

Uma segurança especial foi adicionada às solicitações de PUT, POST e DELETE. Qualquer solicitação que resulte em gravação ou exclusão do banco de dados só poderá ser executada se o sessionID=abc123 está incluído no URI. Os exemplos a seguir mostram como isso procuraria uma solicitação DELETE:

GET /attask/api/v15.0/project?id=4c78...54d0&method=delete&sessionID=abc123
GET /attask/api/v15.0/project/4c78...54d0?method=delete&sessionID=abc123

Autenticação

A API autentica cada solicitação para garantir que o cliente tenha acesso para visualizar ou modificar um objeto solicitado.

A autenticação é realizada transmitindo uma ID de sessão que pode ser fornecida usando um dos seguintes métodos:

Solicitar autenticação de cabeçalho

O método preferido de autenticação é passar um cabeçalho de solicitação chamado SessionID contendo o token de sessão. Isso tem a vantagem de ser seguro contra Falsificação de solicitação entre sites (CSRF) ataques e não interferir no URI para fins de armazenamento em cache.

Veja a seguir um exemplo de um cabeçalho de solicitação:

GET /attask/api/v15.0/project/search
SessionID: abc1234

Solicitar autenticação de parâmetro

Você pode autenticar transmitindo um parâmetro de solicitação chamado sessionID, como mostrado no exemplo a seguir:

GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0?sessionID=abc1234

Autenticação baseada em cookie

A API usa a mesma autenticação baseada em cookies usada pela interface do usuário da Web para o sistema. Onde, se um cliente fizer logon no Workfront usando a interface da Web, qualquer chamada de AJAX feita no mesmo navegador usará a mesma autenticação.

Logon

Usando um nome de usuário e senha válidos, você pode usar a seguinte solicitação para obter uma ID de sessão:

POST /attask/api/v15.0/login?username=admin&password=user

Isso define um cookie para autenticar solicitações futuras, bem como retornar uma resposta JSON com a sessionID recém-criada, a userID do usuário conectado e outros atributos de sessão.

Gerar uma chave de API

Você pode gerar uma Chave de API ao fazer logon no sistema como esse usuário, conforme mostrado no exemplo a seguir:

PUT /attask/api/v15.0/user?action=generateApiKey&username= username&password=password&method=put

Recuperação de uma chave de API gerada anteriormente

Você também pode recuperar uma Chave de API que foi gerada anteriormente para um usuário específico executando getApiKey:

PUT /attask/api/v15.0/user?action=getApiKey&username=user@email.com&password=userspassword&method=put

Você pode usar esse resultado para autenticar qualquer chamada de API adicionando "apiKey" como um parâmetro de solicitação com esse valor no lugar de uma sessionID ou nome de usuário e senha. Isso é benéfico do ponto de vista da segurança.

A solicitação a seguir é um exemplo de recuperação de dados de um projeto usando a apiKey:

GET /attask/api/v15.0/project/abc123xxxxx?apiKey=123abcxxxxxxxxx

Invalidação de uma chave de API

Se o valor apiKey tiver sido comprometido, será possível executar "clearApiKey", que invalida a Chave de API atual, como mostrado no exemplo a seguir:

GET /attask/api/v15.0/user?action=clearApiKey&username=user@email.com&password=userspassword&method=put

Depois de limpa, você pode executar getApiKey novamente para gerar uma nova Chave de API.

Sair

Quando uma sessão é concluída, você pode usar a seguinte solicitação do para fazer logoff do usuário, impedindo qualquer acesso adicional com a sessionID.

GET /attask/api/v15.0/logout?sessionID=abc1234

A sessionID a ser desconectada pode ser especificada como um cookie, cabeçalho de solicitação ou parâmetro de solicitação.

Para fazer logoff de um usuário:

Você sempre deve incluir a sessionID fornecida após o logon ao executar solicitações PUT, POST e DELETE.

Comportamento do GET

Use o método HTTP GET para recuperar um ou vários objetos e executar relatórios.

Recuperando Objetos

Você pode aprimorar uma pesquisa por objetos usando modificadores e filtros.

Recuperando um objeto usando a ID do objeto

Se você souber a ID de um objeto, poderá recuperá-lo acessando seu URI exclusivo. Por exemplo, a solicitação

GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0

retorna uma resposta semelhante à seguinte:

{
    "percentComplete": 0,
    "status": "CUR",
    "priority": 2,
    "name": "Brand New Project",
    "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
}

Você pode recuperar vários objetos na mesma solicitação especificando o parâmetro de solicitação de id e fornecendo uma lista de IDs separadas por vírgulas, como mostrado no exemplo a seguir:

GET /attask/api/v15.0/project?id=4c78...54d0,4c78...54d1

Observe que a solicitação /attask/api/v15.0/project?id=… é igual à solicitação /attask/api/v15.0/project/... solicitação.

Recuperando um objeto usando o URI

Se quiser recuperar um objeto por critérios diferentes da ID, procure o URI.

Por exemplo, você pode usar a seguinte solicitação para retornar uma lista de todos os projetos no sistema:

GET /attask/api/v15.0/project/search

Você pode especificar filtros usando os parâmetros da solicitação como pares de nome-valor. Por exemplo, o exemplo a seguir mostra uma solicitação que localizaria todos os projetos atuais:

GET /attask/api/v15.0/project/search?status=CUR

A solicitação a seguir encontra todas as tarefas que ainda não foram concluídas e que foram atribuídas a um usuário chamado John.

GET /attask/api/v15.0/task/search?percentComplete=100
&percentComplete_Mod=lt &assignedTo:firstName=John

Uso de Modificadores de Pesquisa

A tabela a seguir lista alguns dos modificadores que podem ser usados com a API do Workfront.

…status=cls&status_Mod=eq…

…status=cls&status_Mod=ne…

…percentComplete=50&percentComplete_Mod=get…

…percentComplete=50&percentComplete_Mod=lte…

…description_Mod=isnull…

…description_Mod=notnull…

…name=Workfront&name_Mod=contém…

…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…

Uso de instruções OR

É possível aprimorar uma pesquisa adicionando um parâmetro que inclui "OU", bem como um número para indicar o nível de um filtro ou uma série de filtros.

Uma instrução OR retorna somente registros na chamada à API que atendam aos critérios de filtragem da instrução OR. Os filtros não estão implícitos nos níveis de instrução OU.

Por exemplo, se você deseja filtrar por

Em seguida, use a seguinte chamada de API com suas várias instruções OR:

GET /attask/api/v15.0/task/search?name=Planejamento
&name_Mod=contains
&OU:1:portfolio:name=FixedAssets
&OU:1:portfolio:name_Mod=eq
&OU:1:assignedTo:name=Steve
&OU:1:assignedTo:name_Mod=cicontains
&OU:2:parent:name=Tarefa final
&OU:2:parent:name_Mod=eq

Utilização de parâmetros de filtro

Uma possível armadilha no uso de parâmetros de URL para filtros de pesquisa é que o Workfront analisa determinados parâmetros antes de verificar se há diferentes métodos de autenticação (ou seja, nome de usuário, senha, apiKey, cookie). Quando isso acontece, os parâmetros não são usados como filtros na chamada.

Para evitar esse problema, você pode colocar esses valores em parâmetros de filtro com formatação JSON. Por exemplo, se você deseja filtrar pelo nome de usuário testuser, em vez de usar

/attask/api/v15.0/user/search?username=testuser@workfront.com

passe o parâmetro de URL em um filtro, como mostrado no exemplo a seguir:

/attask/api/v15.0/user/search?filters={"username":"testuser@workfront.com"}

Uso do Parâmetro de solicitação de mapa

Por padrão, os dados retornados de uma pesquisa são uma matriz JSON. Dependendo do caso de uso, pode ser mais eficiente obter o resultado como um objeto JSON indexado pela ID. Isso pode ser feito usando o parâmetro de solicitação map. Por exemplo, a solicitação

/attask/api/v15.0/task/search?map=true

retorna uma resposta indexada por ID semelhante à seguinte:

{
    "data": {
        "4c9a97db0000000f13ee4446b9aead9b": {
            "percentComplete": 0,
            "status": "NEW",
            "name": "first task",
            "ID": "4c9a97db000000f13ee4446b9aead9b",
            "taskNumber": 1 
        },
        "4ca28ba600002024cd49e75bd43cf601": {
            "percentComplete": 0,
            "status": "INP:A",
            "name": "second task",
            "ID": "4ca28ba600002024cd49e75bd43cf601",
            "taskNumber": 2 
        } 
    } 
}

Uso do parâmetro de solicitação de campos

Por padrão, a recuperação de um objeto retorna somente o subconjunto de campos usado com mais frequência.

Você pode usar o parâmetro de solicitação de campos para especificar que uma lista separada por vírgulas de campos específicos seja retornada. Por exemplo, a solicitação

/attask/api/v15.0/task/search?fields=plannedStartDate,priority

retorna uma resposta semelhante à seguinte:

{
    "priority": 2,
    "name": "first task",
    "ID": "4c7c08fa000000ff924e298ee148df4",
    "plannedStartDate": "30/08/2010:00:00:000-0600" 
}

Para obter uma lista de referências de campo possíveis, consulte  API Explorer

Pesquisando Objetos Aninhados

Você pode pesquisar objetos aninhados. Por padrão, objetos aninhados são retornados somente com o nome e a ID. Por exemplo, para obter todos os problemas junto com seus proprietários, use a seguinte solicitação:

/attask/api/v15.0/issue/search?fields=proprietário

Se forem necessárias mais informações, é possível solicitar um campo aninhado usando a sintaxe de dois pontos. Por exemplo, a solicitação a seguir pesquisa todos os problemas, juntamente com o nome, a ID, o título e o número de telefone do proprietário

/attask/api/v15.0/issue/search?fields=proprietário:título,proprietário:phoneNumber

e retorna o seguinte:

{
    "name": "um problema importante",
    "ID": "4c78285f0000908ea8cfd66e084939f",
    "owner": {
        "title": "Operations Specialist",
        "phoneNumber": "555-1234",
        "name": "Usuário administrador",
        "ID": "4c76ed7a0000054c172b2c2d9f7f81c3" 
    } 
}

Recuperando coleções aninhadas

Você pode recuperar coleções aninhadas de objetos. Por exemplo, para obter um projeto com todas as suas tarefas, use a seguinte solicitação:

/attask/api/v15.0/project/search?fields=tarefas

A solicitação a seguir obtém atribuições de tarefas:

/attask/api/v15.0/task/search?fields=atribuições

Pesquisa de vários campos aninhados

Por padrão, somente o nome e a ID de cada tarefa são retornados, mas campos aninhados adicionais podem ser especificados com a sintaxe de dois pontos. Para exibir todos os campos disponíveis para um objeto ou coleção relacionada, basta anexar dois pontos e um asterisco à referência do objeto/coleção.

/attask/api/v15.0/task/search?fields=atribuições:*

Recuperação de dados personalizados

Você pode recuperar campos de dados personalizados usando o prefixo "DE:". Por exemplo, para solicitar um projeto com um parâmetro chamado "CustomText", use a seguinte solicitação:

/attask/api/v15.0/project/search?fields=DE:CustomText

que retornaria

{
    "name": "projeto de dados personalizado",
    "ID": "4c9a954f000000afad0687d7b1b4e43",
    "DE:CustomText": "task b" 
}

Você também pode recuperar todos os dados personalizados de um objeto solicitando o campo parameterValues. Por exemplo,

/attask/api/v15.0/project/search?fields=parameterValues

retorna dados semelhantes ao seguinte:

{
    "name": "projeto de dados personalizado",
    "ID": "4c9a954f000000afad0687d7b1b4e43",
    parameterValues: { 
        "DE:CustomText": "task b", 
        "DE:CustomNumber": 1.4, 
        "DE:CustomCheckBoxes": ["first", "second", "third"] 
    } 
}

Uso de Consultas Nomeadas

Alguns tipos de objeto têm pesquisas nomeadas que são executadas com frequência e estão disponíveis ao anexar o nome da consulta ao final do URI do tipo de objeto. Por exemplo, a solicitação a seguir recupera os itens de trabalho (tarefas e problemas) aos quais o usuário está atribuído no momento:

/attask/api/v15.0/work/myWork

As consultas nomeadas suportam a solicitação do parâmetro de campos para recuperar campos adicionais. Algumas consultas nomeadas também aceitam filtros adicionais. Para obter uma lista de consultas nomeadas permitidas para um objeto, consulte a guia Ação para o objeto no [API Explorer](https://experienceleague.adobe.com/docs/workfront/using/adobe-workfront-api/api-general-information/api-explorer.html?lang=pt-BR).

Usar Count

Você pode usar count para retornar o número de resultados que correspondem à sua consulta. Isso pode ser útil quando você não precisa dos dados nos resultados. Ao retornar apenas a contagem, o servidor pode processar a solicitação mais rapidamente e economizar largura de banda. Por exemplo, a solicitação

GET /attask/api/v15.0/project/count?status=CUR

retorna o número de resultados no seguinte formato:

{
    "count": 3 
}

Retornar uma contagem é uma transferência de dados muito menor do que se os objetos completos forem retornados. A sintaxe é idêntica ao comando search.

Solicitar um relatório

Você pode executar uma solicitação de relatório, onde somente a agregação de algum campo é desejada com um ou mais agrupamentos. Como mostrado no exemplo a seguir, a sintaxe do relatório é igual à sintaxe da API SOAP:

GET /attask/api/v15.0/hour/report?project:name_1_GroupBy=true&hours_AggFunc=sum

que retorna o seguinte resultado

{
    "Primeiro projeto": { 
        "sum_hours": 15 
    }, 
     "Segundo projeto": { 
        "sum_hours": 30 
    } 
}

A adição do parâmetro $$ROLLUP=true inclui um total em cada nível de agrupamento:

{
    "Primeiro projeto": { 
        "sum_hours": 15 
    }, 
    "Segundo projeto": { 
        "sum_hours": 30 
    }, 
    "$$ROLLUP": { 
        "sum_hours": 45 
    } 
}

Classificação dos resultados da consulta na API

Você pode classificar os resultados por qualquer campo se anexar o seguinte à chamada de API:

&entryDate_Sort=asc

Por exemplo, se você deseja classificar por Data de início planejada da tarefa, remova entryDate e substitua-a por plannedCompletionDate.

Isso funciona para a maioria dos campos no Workfront.

Consideração dos limites de consulta

Ao consultar um objeto, deve-se levar em consideração a relação entre objetos relacionados e as limitações de pesquisa. Por exemplo, como mostrado na tabela a seguir, uma consulta de projetos não pode retornar mais de 2.000 projetos. Esses 2.000 projetos são considerados "objetos principais". Se você consultar o campo Tasks nos projetos, o campo Tasks, que é uma coleção, se tornará um objeto secundário ao projeto de objeto principal. Uma consulta para o campo Tarefas pode incluir milhares de tarefas em projetos. No total, o número combinado de objetos (projetos e tarefas) retornados não pode exceder o máximo de 50.000.

Para garantir o desempenho ideal, a tabela a seguir mostra as limitações impostas às solicitações de pesquisa.

Utilização de respostas paginadas using-paginated-responses

Para substituir a limitação de consulta Número Padrão de Resultados e permitir 200 resultados, você pode incluir a variável $$LIMIT=200 no query, conforme mostrado no exemplo a seguir:

GET /attask/api/v15.0/project/search?$$LIMIT=200

Para garantir a confiabilidade e o desempenho de outros locatários no sistema, o limite máximo de resultados permitido por consulta é de 2000 objetos. Tentar especificar um limite maior resultará em uma IllegalArgumentException mensagem de erro.

Portanto, recomendamos que você considere usar respostas paginadas para grandes conjuntos de dados. Para especificar o primeiro resultado que deve ser retornado, adicione o $$FIRST filtro. Por exemplo, a solicitação a seguir retorna os resultados 201-250 para uma consulta:

GET /attask/api/v15.0/project/search?$$FIRST=200&$$LIMIT=50

Observe que no exemplo acima, $$FIRST=200 retorna o resultado 201. $$FIRST=0 retornaria o primeiro resultado. Pode ser útil pensar no valor $$FIRST como o número de resultados que você deseja ignorar antes de retornar os resultados.

Para garantir que seus resultados sejam paginados corretamente, use um parâmetro de classificação. Isso permite que os resultados sejam retornados na mesma ordem, para que a paginação não repita ou ignore os resultados. Por exemplo, para classificar usando a ID de objeto, use ID_Sort=asc.

Criação de uma regra de acesso

Você pode criar uma regra de acesso para determinar quem pode acessar um objeto. Veja a seguir exemplos de regras de acesso que você pode definir:

Para definir um projeto para que ele seja compartilhado somente com um usuário com ID "abc123", use a seguinte solicitação:

GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?method=put &updates={ accessRules: [ {accessID: 'abc123', accessorObjCode: 'USER', coreAction: 'VIEW'} ] }

Como alternativa, para compartilhar somente com uma nova pessoa e manter as permissões existentes intactas:

GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxx/share?method=put&accessorID=abc123&accessorObjCode=USER&coreAction=VIEW

Para recuperar as regras de acesso existentes:

GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxx?fields=accessRules:*

Comportamento do POST

POST insere um novo objeto. A sintaxe é idêntica ao PUT, mas com algumas exceções. Como o novo objeto ainda não existe, ele não tem uma ID. Por esse motivo, o URI não inclui a ID.

Criação de um objeto

Veja a seguir um exemplo de uma solicitação para criar um novo projeto:

POST /attask/api/v15.0/project?name=Novo projeto

A resposta inclui o projeto recém-criado, a nova ID e todos os outros campos especificados.

Copiando um Objeto

Alguns objetos oferecem suporte à cópia. Para esses tipos de objeto, é possível criar novos objetos publicando com um parâmetro copySourceID. Por exemplo, a solicitação a seguir copia o projeto fornecido e lhe dá um novo nome:

POST /attask/api/v15.0/project?copySourceID=4c7...&name=Copied Project

Carregando Documentos

Você pode fazer upload de documentos por meio do seguinte URL da API:

POST /attask/api/v15.0/upload

A API espera que o tipo de conteúdo seja multipart/form-data. O nome do parâmetro do arquivo deve ser uploadedFile. O servidor retorna os seguintes dados JSON:

{
    "handle": "4c7c08fa0000002ff924e298ee148df4"
}

Você pode usar o identificador e publicar no seguinte URL ao criar um documento do Workfront:

POST /attask/api/v15.0/document?updates={
    name: aFileName,
    handle: abc...123, (manipule do upload de arquivo)
    docObjCode: PROJ, (ou TASK, OPTASK, etc.)
    objID: abc.123,
    currentVersion:{version:v1.0,fileName:aFileName}
}

Comportamento do PUT

PUT é usado para atualizar um objeto existente.

A resposta de um PUT é idêntica a uma GET. Em ambos os casos, o servidor retorna o novo estado do objeto após a atualização. Todas as regras usadas para alterar uma resposta a uma solicitação do GET também funcionam com o PUT, como especificar campos adicionais a serem retornados, dados personalizados etc.

Editando Objetos

As atualizações de objetos são sempre feitas por ID usando o URI exclusivo do objeto. Os campos que serão atualizados são especificados como parâmetros de solicitação. Por exemplo, para alterar o nome de um projeto, você pode enviar uma solicitação semelhante à seguinte:

PUT /attask/api/v15.0/project/4c7...?name=Novo nome do projeto 
PUT /attask/api/v15.0/project?id=4c7...&name=Novo nome do projeto

Como a atualização requer uma ID, essa operação falhará (sem inserção) se o objeto não existir no servidor.

Especificação de edições de JSON

Como mostrado no exemplo a seguir, você pode usar o parâmetro de solicitação de atualizações para especificar os campos a serem atualizados usando a sintaxe JSON:

PUT /attask/api/v15.0/project/4c7...?atualizações= 
{
     name: "Novo nome do projeto", 
     status: "CUR", 
     .. 
}

Fazer atualizações aninhadas

Alguns objetos têm coleções de propriedade privada que podem ser atualizadas. Por exemplo, o exemplo a seguir demonstra como substituir as atribuições existentes para uma determinada tarefa:

PUT /attask/api/v15.0/task/4c7...?atualizações= 
{
    atribuições: [ 
        { 
            assignedToID: "2222...54d0, 
            assignmentPercent: 50,0 
        },{ 
            roleID: "1111...54d0"
        } 
    ] 
}

O exemplo a seguir torna um projeto uma fila de Help Desk pública. Observe que as propriedades existentes da fila são substituídas.

PUT /attask/api/v15.0/project/4c7...?atualizações= 
{ 
    queueDef: { 
        isPublic: 1 
    } 
}

Uso do Parâmetro de Solicitação de Ação

Alguns objetos oferecem suporte a ações adicionais que podem ser executadas, além de edições simples. Você pode especificar essas ações usando o parâmetro action request. Por exemplo, a solicitação a seguir recalcula a linha do tempo de um determinado projeto:

PUT /attask/api/v15.0/project/4c7...?action=calculateTimeline

ou

PUT /attask/api/v15.0/project/4c7.../calculateTimeline 

Movendo Objetos

A seguir é apresentada a sintaxe para mover uma tarefa de um projeto para outro:

PUT /attask/api/v15.0/task/4c7.../move?projectID=5d8...

Um exemplo para cada tipo de ação é fornecido aqui: (??)

PUT /attask/api/v15.0/project/1234/approveApproval

PUT /attask/api/v15.0/project/1234/calculateFinance

PUT /attask/api/v15.0/project/1234/calculateTimeline

PUT /attask/api/v15.0/project/1234/calculateDataExtension

PUT /attask/api/v15.0/project/1234/recallApproval

PUT /attask/api/v15.0/project/1234/rejectApproval

PUT /attask/api/v15.0/task/1234/move

PUT /attask/api/v15.0/workitem/1234/markViewed

Somente a ação de mover requer a identificação de atributos adicionais para especificar o projeto para o qual o item de trabalho deve ser movido.

Veja a seguir um exemplo de cada tipo de ação:

PUT /attask/api/v15.0/project/1234?method=put&updates={accessRules:[{accessID: 'abc123', accessorObjCode: 'USER', coreAction: 'VIEW'}]}

Objetos de Compartilhamento

O exemplo a seguir demonstra a sintaxe para o compartilhamento de um projeto com uma equipe:

PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx/share?accessorID=123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&accessorObjCode=TEAMOB

Ao editar um objeto, você pode substituir todas as regras de acesso em um objeto fazendo um PUT e enviando atualizações semelhantes ao seguinte exemplo:

PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?method=PUT&updates={accessRules:[{accessorID:'123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',accessorObjCode:'TEAMOB',coreAction:'VIEW'}]}

O exemplo a seguir mostra a sintaxe para mover uma tarefa de um projeto para outro:

PUT /attask/api/v15.0/task/4c7.../move?projectID=5d8...

Comportamento do DELETE

DELETE remove um objeto. Em todos os casos, o URI pode incluir o parâmetro force=true para fazer com que o servidor remova os dados especificados e seus dependentes. No exemplo a seguir, uma tarefa é excluída executando o método HTTP DELETE em um URI:

DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0 
DELETE /attask/api/v15.0/task?id=4c78821c0000d6fa8d5e52f07a1d54d0 
DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0?force=true 
DELETE /attask/api/v15.0/task?id=4c78821c0000d6fa8d5e52f07a1d54d0?force=true

Atualizações em massa

Uma instrução de atualização em massa atualiza vários objetos ao mesmo tempo em uma única chamada de API. Uma chamada de API de criação em massa é criada de forma semelhante a uma chamada de atualização normal, como mostrado nos exemplos a seguir:

PUT /attask/api/v15.0/proj?updates=[{"name":"Test_Project_1"},{"name":"Test_Project_2"}]&method=POST&apiKey=123ab-cxxxxxxxxxxxxxxxxxxxxxxxxxx

que resulta em um retorno semelhante ao seguinte:

dados: [{
    ID: "53ff8d3d003b438b57a8a784df38f6b3",
    name: "Test_Project_1",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "28/08/2014 T11:00:00:000-0400",
    plannedStartDate: "28/08/2014 T11:00:00:000-0400",
    prioridade: 0,
    projectsCompletionDate: "28/08/2014 T16:12:00:000-0400",
    status: "CUR"
},
{
    ID: "53ff8d49003b43a2562aa34eea3b6b10",
    name: "Test_Project_2",
    objCode: "PROJ",
    percentComplete: 0usi,
    plannedCompletionDate: "28/08/2014 T11:00:00:000-0400",
    plannedStartDate: "28/08/2014 T11:00:00:000-0400",
    prioridade: 0,
    projectsCompletionDate: "28/08/2014 T16:12:00:000-0400",
    status: "CUR"
}]

Você também pode fazer uma atualização em massa semelhante ao seguinte:

PUT /attask/api/v15.0/proj?Umethod=PUT&updates=[{"ID":"123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxx","name":"Test_Project_1_ Edit"},{"ID":"123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","name":"Test_Project_2_Edit"}] apiKey=123abcxxxxxxxxxxxxxxxxxxxxxxxxxxx

que resulta em um retorno semelhante ao seguinte:

dados: [ {
     ID: "53ff8e15003b461d4560f7f65a440078",
     name: "Test_Project_1_Edit",
     objCode: "PROJ",
     percentComplete: 0,
     plannedCompletionDate: "28/08/2014 T11:00:00:000-0400",
     plannedStartDate: "28/08/2014 T11:00:00:000-0400",
     prioridade: 0,
     projectsCompletionDate: "28/08/2014 T16:16:00:000-0400",
     status: "CUR"
},
{
    ID: "53ff8e19003b46238a58d303608de502",
    name: "Test_Project_2_Edit",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "28/08/2014 T11:00:00:000-0400",
    plannedStartDate: "28/08/2014 T11:00:00:000-0400",
    prioridade: 0,
    projectsCompletionDate: "28/08/2014 T16:16:00:000-0400",
    status: "CUR"
}]

Se quiser que todas as operações aconteçam na mesma transação, adicione "atomic=true" à chamada da API em lote como um parâmetro de solicitação. Dessa forma, se qualquer uma das operações falhar, todas as operações serão revertidas.