DocumentazioneWorkfrontGuida di Workfront

Nozioni di base sulle API

Last update: Thu Jun 27 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Argomenti:

Creato per:

  • Sviluppatore

L’obiettivo per l’API di Adobe Workfront è semplificare la creazione di integrazioni con Workfront introducendo un’architettura REST-ful che funziona tramite HTTP. Questo documento presuppone che tu abbia familiarità con le risposte REST e JSON e descrive l’approccio adottato dall’API Workfront.

Acquisire familiarità con lo schema Workfront ti aiuterà a comprendere le relazioni tra database che possono essere utilizzate per estrarre dati da Workfront a scopo di integrazione.

Limiti e linee guida

Per garantire prestazioni coerenti del sistema Workfront on-demand, l’API Workfront limita i thread API simultanei. Questo guardrail impedisce i problemi di sistema causati da chiamate API abusive. L’ambiente Sandbox dispone dello stesso limite di thread API simultanei, che consente a clienti e partner di testare con precisione le chiamate API prima di rilasciare il codice in produzione.

Per gli ambienti di produzione, anteprima e test delle unità, le richieste degli utenti finali hanno una lunghezza URI massima di 8892 byte, in quanto vengono instradate tramite la rete CDN di Workfront (Akamai). Questo limite si applica solo agli URI instradati attraverso la rete CDN.

NOTE
questo limite non è applicabile agli ambienti sandbox perché gli ambienti sandbox non vengono instradati attraverso la rete CDN.

Esclusione di responsabilità

Qualsiasi utilizzo dell’API deve essere testato nell’ambiente beta di Workfront prima di essere eseguito nell’ambiente di produzione. Se un cliente utilizza l’API per un processo che Workfront ritiene ragionevolmente oneroso per il software on-demand (ovvero, il processo causa un effetto sostanzialmente negativo sulle prestazioni del software per altri clienti), Workfront si riserva il diritto di richiedere che il cliente interrompa tale processo. Se il cliente non si conforma e il problema persiste, Workfront si riserva il diritto di terminare il processo.

URL API WORKFRONT

Per informazioni sull’URL che utilizzerai per chiamare l’API di Workfront, consulta Formato del dominio per le chiamate API di Adobe Workfront.

Nozioni di base su REST

Questa sezione fornisce un’introduzione di alto livello su come interagire con l’API REST di Workfront per i seguenti principi REST:

URI oggetto

A ogni oggetto nel sistema viene assegnato un URI univoco costituito dal tipo di oggetto e dall'ID. Gli esempi seguenti mostrano gli URI che descrivono tre oggetti univoci:

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

Il tipo di oggetto non distingue tra maiuscole e minuscole e può essere l'abbreviazione ObjCode (ad esempio proj) o il nome dell'oggetto alternativo (project).

Per un elenco dei ObjCodes validi, vedi  API Explorer.

Operazioni

Gli oggetti vengono manipolati inviando una richiesta HTTP al relativo URI univoco. L'operazione da eseguire è specificata dal metodo HTTP.

I metodi HTTP standard corrispondono alle operazioni seguenti:

  • GET : recupera un oggetto per ID, cerca tutti gli oggetti tramite query, esegue report o esegue query con nome.
  • POST - Inserisce un nuovo oggetto
  • PUT - Modifica un oggetto esistente
  • DELETE - Elimina un oggetto

Per ovviare alle carenze dei client o ai limiti di lunghezza del protocollo, il parametro di metodo può essere utilizzato per ignorare il comportamento HTTP. Ad esempio, un’operazione di GET può essere implementata inserendo il seguente URI:

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

Risposta

A ogni richiesta viene fornita una risposta in formato JSON. La risposta dispone di un attributo dati se la richiesta ha avuto esito positivo o di un attributo di errore se si è verificato un problema. Ad esempio, la richiesta

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

restituisce una risposta JSON simile alla seguente:

{
    "data": [
        {
            "percentComplete": 0,
            "status": "CUR",
            "priorità": 2,
            "name": "Brand New Project",
            "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
        } 
    ] 
}
NOTE
Quando si esegue una richiesta GET tramite la barra degli indirizzi del browser, non è necessario includere sessionID come parte della richiesta.

È stata aggiunta una protezione speciale per le richieste di PUT, POST e DELETE. Qualsiasi richiesta che porti alla scrittura o all’eliminazione dal database può essere eseguita solo se sessionID=abc123 è incluso nell’URI. Gli esempi seguenti mostrano come dovrebbe essere una richiesta 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

Autenticazione

L’API autentica ogni richiesta per garantire che il client abbia accesso alla visualizzazione o alla modifica di un oggetto richiesto.

L’autenticazione viene eseguita trasmettendo un ID sessione che può essere assegnato utilizzando uno dei seguenti metodi:

Autenticazione intestazione richiesta

Il metodo preferito per l’autenticazione consiste nel trasmettere un’intestazione di richiesta denominata SessionID contenente il token di sessione. Questo ha il vantaggio di essere al sicuro CSRF (Cross-Site Request Forgery) attacchi e non interferire con l’URI a scopo di caching.

Di seguito è riportato un esempio di intestazione di richiesta:

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

Richiedi autenticazione parametro

Puoi eseguire l’autenticazione trasmettendo un parametro di richiesta denominato sessionID, come illustrato nell’esempio seguente:

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

L’API utilizza la stessa autenticazione basata su cookie utilizzata dall’interfaccia web per il sistema. Se un client accede a Workfront utilizzando l’interfaccia utente web, tutte le chiamate AJAX effettuate dall’interno dello stesso browser utilizzano la stessa autenticazione.

NOTE
Al fine di proteggere da possibili attacchi CSRF (Cross Site Request Forgery), questo metodo di autenticazione è disponibile solo per le operazioni di sola lettura.

Accedi

IMPORTANT
Workfront non consiglia più di utilizzare /login endpoint o chiavi API. Utilizza invece uno dei seguenti metodi di autenticazione:
  • Autenticazione server con JWT
  • Autenticazione utente con OAuth2
Per istruzioni sulla configurazione di questi metodi di autenticazione, consulta Creazione di applicazioni OAuth2 per le integrazioni Workfront
Per istruzioni sull’utilizzo dell’autenticazione server in Workfront, consulta Configurare e utilizzare le applicazioni OAuth 2 personalizzate della tua organizzazione utilizzando il flusso JWT
Per istruzioni sull’utilizzo dell’autenticazione utente in Workfront, consulta Configurare e utilizzare le applicazioni OAuth 2 personalizzate della tua organizzazione utilizzando il flusso del codice di autorizzazione
NOTE
La procedura descritta in questa sezione si applica solo alle organizzazioni che non sono ancora state caricate su Adobe Business Platform. L’accesso a Workfront tramite l’API Workfront non è disponibile se l’organizzazione è stata integrata in Adobe Business Platform.
Per un elenco delle procedure che differiscono in base al fatto che la tua organizzazione sia stata integrata o meno in Adobe Business Platform, consulta Differenze di amministrazione basate su piattaforma (Adobe Workfront/Adobe Business Platform).

Utilizzando un nome utente e una password validi, puoi utilizzare la seguente richiesta per ottenere un ID sessione:

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

Questo imposta un cookie per autenticare le richieste future e restituire una risposta JSON con il sessionID appena creato, l’userID dell’utente connesso e altri attributi di sessione.

NOTE
Se hai un utente API designato che è anche un amministratore, Workfront ti consiglia vivamente di utilizzare una chiave API per accedere.

Generazione di una chiave API

Puoi generare una chiave API quando accedi al sistema come tale utente, come illustrato nell’esempio seguente:

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

Recupero di una chiave API generata in precedenza

Puoi anche recuperare una chiave API che è stata generata in precedenza per un particolare utente eseguendo getApiKey:

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

Puoi quindi utilizzare questo risultato per autenticare qualsiasi chiamata API aggiungendo "apiKey" come parametro di richiesta con questo valore al posto di sessionID o nome utente e password. Questo è vantaggioso dal punto di vista della sicurezza.

La seguente richiesta è un esempio di recupero di dati da un progetto utilizzando apiKey:

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

Annullamento della validità di una chiave API

Se il valore apiKey è stato compromesso, puoi eseguire "clearApiKey" che invalida la chiave API corrente, come illustrato nell’esempio seguente:

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

Una volta deselezionata, puoi eseguire nuovamente getApiKey per generare una nuova chiave API.

Esci

Al termine di una sessione, puoi utilizzare la seguente richiesta per disconnettere l’utente, impedendo qualsiasi ulteriore accesso con sessionID.

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

Il valore sessionID da disconnettere può essere specificato come cookie, intestazione di richiesta o parametro di richiesta.

Per disconnettersi da un utente:

  1. Passa alla schermata di accesso, ma non accedi.

  2. Modifica l’URL in /attask/api/v15.0/project/search.
    Nota che la pagina non è stata trovata.

  3. Sostituisci la parola ricerca con login?username=admin&password=user, sostituendo username e password con admin e *utente
    *Questa sessione viene memorizzata nel browser come cookie e non deve essere ripetuta in ogni richiesta successiva del GET.

  4. Ripristina l’URL /attask/api/v15.0/project/search.

  5. Osserva la risposta fornita.

Quando esegui richieste PUT, POST e DELETE, devi sempre includere l’ID sessione fornito dopo l’accesso.

Comportamento GET

Utilizzare il metodo HTTP GET per recuperare uno o più oggetti ed eseguire i report.

Recupero di oggetti

È possibile migliorare la ricerca di oggetti utilizzando modificatori e filtri.

Recupero di un oggetto mediante l'ID oggetto

Se si conosce l'ID di un oggetto, è possibile recuperarlo accedendo al relativo URI univoco. Ad esempio, la richiesta

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

restituisce una risposta simile alla seguente:

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

Puoi recuperare più oggetti nella stessa richiesta specificando il parametro della richiesta ID e fornendo un elenco separato da virgole di ID, come mostrato nell’esempio seguente:

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

Nota che la richiesta /attask/api/v15.0/project?id=… è uguale alla richiesta /attask/api/v15.0/project/... richiesta.

Recupero di un oggetto tramite l'URI

Se desideri recuperare un oggetto in base a criteri diversi dall’ID, puoi cercare l’URI.

Ad esempio, puoi utilizzare la seguente richiesta per restituire un elenco di tutti i progetti nel sistema:

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

Puoi specificare i filtri utilizzando i parametri della richiesta come coppie nome-valore. Ad esempio, l’esempio seguente mostra una richiesta che troverebbe tutti i progetti correnti:

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

La richiesta seguente trova tutte le attività non ancora completate e assegnate a un utente di nome John.

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

Utilizzo dei modificatori di ricerca

Nella tabella seguente sono elencati alcuni dei modificatori che è possibile utilizzare con l’API Workfront.

Modificatore
Descrizione
Esempio
eq
restituisce risultati con stato chiuso
…status=cls&status_Mod=eq…
ne
restituisce risultati che non sono nello stato chiuso
…status=cls&status_Mod=ne…
gte
restituisce risultati con una percentuale di completamento maggiore o uguale a 50
…percentComplete=50&percentComplete_Mod=get…
lte
restituisce risultati con una percentuale di completamento minore o uguale a 50
…percentComplete=50&percentComplete_Mod=lte…
isnull
restituisce risultati in cui la descrizione è Null
…description_Mod=isnull…
notnull
restituisce risultati in cui la descrizione non è Null
…description_Mod=notnull…
contiene
restituisce i risultati in cui il nome contiene "Workfront"
…name=Workfront&name_Mod=contiene…
tra
restituisce risultati con una data di inserimento compresa negli ultimi 7 giorni
…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…
NOTE
Le richieste di ricerca fanno distinzione tra maiuscole e minuscole. Se ricevi un errore, assicurati   _Mod e _Intervallo utilizzare le maiuscole corrette.

Utilizzo delle istruzioni OR

Puoi migliorare una ricerca aggiungendo un parametro che include "OR" e un numero per indicare il livello di un filtro o di una serie di filtri.

Un’istruzione OR restituisce solo i record nella chiamata API che soddisfano i criteri di filtro dell’istruzione OR. I filtri non sono impliciti tra i livelli di istruzione OR.

Ad esempio, per filtrare

  • Attività il cui nome contiene "Planning" OR
  • Attività in un portfolio denominato "FixedAssets" E assegnate a qualcuno con un nome contenente "Steve" O
  • Attività con un'attività padre denominata "Attività finale"

quindi utilizza la seguente chiamata API con le sue più istruzioni OR:

GET /attask/api/v15.0/task/search?name=Planning
&name_Mod=contains
&O:1:portfolio:name=Cespiti
&O:1:portfolio:name_Mod=eq
&O:1:assignedTo:name=Steve
&O:1:assignedTo:name_Mod=cicontains
&O:2:parent:name=Attività finale
&O:2:parent:name_Mod=eq

Utilizzo dei parametri del filtro

Un potenziale problema nell’utilizzo dei parametri URL per i filtri di ricerca è che Workfront analizza alcuni parametri prima di verificare la presenza di diversi metodi di autenticazione (ad esempio nome utente, password, apiKey, cookie). In questo caso, i parametri non vengono utilizzati come filtri nella chiamata di.

Per evitare questo problema, puoi inserire questi valori nei parametri del filtro con formattazione JSON. Ad esempio, per filtrare in base al nome utente testuser, anziché utilizzare

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

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

Utilizzo del parametro di richiesta mappa

Per impostazione predefinita, i dati restituiti da una ricerca sono un array JSON. A seconda del caso d’uso, potrebbe essere più efficiente ottenere il risultato come oggetto JSON indicizzato per ID. Questa operazione può essere eseguita utilizzando il parametro della richiesta mappa. Ad esempio, la richiesta

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

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

Utilizzo del parametro di richiesta Fields

Per impostazione predefinita, il recupero di un oggetto restituisce solo il sottoinsieme di campi più comunemente utilizzato.

Puoi utilizzare il parametro di richiesta fields per specificare che venga restituito un elenco separato da virgole di campi specifici. Ad esempio, la richiesta

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

{
    "priorità": 2,
    "name": "first task",
    "ID": "4c7c08fa0000002ff924e298ee148df4",
    "plannedStartDate": "2010-08-30T09:00:00:000-0600" 
}
NOTE
Questi nomi di campo fanno distinzione tra maiuscole e minuscole.

Per un elenco dei possibili riferimenti ai campi, vedi  API Explorer

Ricerca di oggetti nidificati

È possibile cercare oggetti nidificati. Per impostazione predefinita, gli oggetti nidificati vengono restituiti solo con il nome e l’ID. Ad esempio, per ottenere tutti i problemi insieme ai relativi proprietari, utilizza la seguente richiesta:

/attask/api/v15.0/issue/search?fields=owner

/attask/api/v15.0/issue/search?fields=owner:title,owner:phoneNumber

{
    "name": "an important issue",
    "ID": "4c78285f00000908ea8cfd66e084939f",
    "owner" (proprietario): {
        "title": "Specialista delle operazioni",
        "phoneNumber": "555-1234",
        "name": "Admin User",
        "ID": "4c76ed7a0000054c172b2c2d9f7f81c3" 
    } 
}

Recupero raccolte nidificate

È possibile recuperare insiemi nidificati di oggetti. Ad esempio, per ottenere un progetto con tutte le relative attività, utilizza la seguente richiesta:

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

/attask/api/v15.0/task/search?fields=assignments

Ricerca di più campi nidificati

Per impostazione predefinita, vengono restituiti solo il nome e l’ID di ogni attività, ma è possibile specificare ulteriori campi nidificati con la sintassi dei due punti. Per visualizzare tutti i campi disponibili per un oggetto o un insieme correlato, è sufficiente aggiungere due punti e un asterisco al riferimento all'oggetto o all'insieme.

/attask/api/v15.0/task/search?fields=assegnazioni:*

Recupero di dati personalizzati

Puoi recuperare campi dati personalizzati con il prefisso "DE:". Ad esempio, per richiedere un progetto con un parametro denominato "CustomText", utilizza la seguente richiesta:

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

{
    "name": "progetto di dati personalizzati",
    "ID": "4c9a954f0000001afad0687d7b1b4e43",
    "DE:CustomText": "task b" 
}

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

{
    "name": "progetto di dati personalizzati",
    "ID": "4c9a954f0000001afad0687d7b1b4e43",
    parameterValues: { 
        "DE:CustomText": "task b", 
        "DE:CustomNumber": 1,4 
        "DE:CustomCheckBoxes": ["first", "second", "third"] 
    } 
}

Utilizzo di query denominate

Alcuni tipi di oggetto dispongono di ricerche denominate che vengono comunemente eseguite e sono disponibili aggiungendo il nome della query alla fine dell'URI del tipo di oggetto. Ad esempio, la seguente richiesta recupera gli elementi di lavoro (attività e problemi) a cui l’utente è attualmente assegnato:

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

Utilizzo di Count

È possibile utilizzare count per restituire il numero di risultati che corrispondono alla query. Questo può essere utile quando non hai bisogno dei dati nei risultati. Restituendo solo il conteggio, il server può elaborare la richiesta più rapidamente e risparmiare larghezza di banda. Ad esempio, la richiesta

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

{
    "count": 3 
}

Richiesta di un rapporto

È possibile eseguire una richiesta di rapporto, in cui si desidera ottenere solo l’aggregato di alcuni campi con uno o più raggruppamenti. Come mostrato nell’esempio seguente, la sintassi del rapporto è la stessa della sintassi per l’API SOAP:

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

{
    "Primo progetto": { 
        "sum_hours": 15 
    }, 
     "Secondo progetto": { 
        "sum_hours": 30 
    } 
}

{
    "Primo progetto": { 
        "sum_hours": 15 
    }, 
    "Secondo progetto": { 
        "sum_hours": 30 
    }, 
    "$$ROLLUP": { 
        "sum_hours": 45 
    } 
}

Ordinamento dei risultati della query nell’API

Puoi ordinare i risultati in base a qualsiasi campo se aggiungi quanto segue alla chiamata API:

&entryDate_Sort=asc

Se ad esempio si desidera ordinare in base all'attività Data inizio pianificata, rimuovere entryDate e sostituirlo con plannedCompletionDate.

Questo funziona per la maggior parte dei campi in Workfront.

Considerazione dei limiti delle query

Quando si esegue una query su un oggetto, è necessario prestare particolare attenzione alla relazione tra oggetti correlati e limitazioni della ricerca. Ad esempio, come illustrato nella tabella seguente, una query per progetti può restituire non più di 2.000 progetti. Questi 2.000 progetti sono considerati "oggetti primari". Se si esegue una query per il campo Attività dei progetti, il campo Attività, che è un insieme, diventa un oggetto secondario dell'oggetto principale Project. Una query per il campo Attività può includere migliaia di attività nei progetti. In totale, il numero combinato di oggetti (progetti e attività) restituiti non può superare il massimo di 50.000.

Per garantire prestazioni ottimali, la tabella seguente mostra le limitazioni imposte alle richieste di ricerca.

Risultato della query
Limitazione
Descrizione
Numero predefinito di risultati
100
Se nel filtro query non è specificato alcun limite (ad esempio, $$LIMIT), il risultato non può contenere più di 100 oggetti primari.
Consulta Utilizzo di risposte impaginate per istruzioni su come ignorare questa limitazione.
Numero massimo di risultati
2.000
Il filtro query (ovvero $$LIMIT) può restituire non più di 2.000 risultati. Vedi "Risposte impaginate" per ulteriori informazioni.
Profondità massima campo
4
Quando si identificano i campi che si desidera visualizzare, non è possibile allontanarsi di più di quattro livelli dall'oggetto di cui si esegue la query.
Numero massimo di oggetti
50.000
Il set di risultati non può includere 50000 oggetti primari e secondari.
Numero massimo di campi
1.000.000
Se il set di risultati è inferiore a 50000 oggetti, i risultati possono includere al massimo 1.000.000 campi.
Numero massimo di creazioni/aggiornamenti batch
100
Il limite massimo per la creazione o l’aggiornamento del batch è 100.

Utilizzo di risposte impaginate using-paginated-responses

Per ignorare il limite predefinito della query Numero di risultati e consentire l'immissione di 200 risultati, è possibile includere $$LIMIT=200 nella query, come illustrato nell’esempio seguente:

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

Per garantire affidabilità e prestazioni per altri tenant nel sistema, il limite massimo di risultati consentito per query è di 2.000 oggetti. Se si tenta di specificare un limite più ampio, verrà generato un IllegalArgumentException messaggio di errore.

Pertanto, consigliamo di considerare l’utilizzo di risposte impaginate per set di dati di grandi dimensioni. Per specificare il primo risultato da restituire, aggiungere il $$FIRST filtro. Ad esempio, la seguente richiesta restituisce i risultati 201-250 per una query:

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

Nell’esempio precedente, $$FIRST=200 restituisce il risultato 201st. $$FIRST=0 restituirebbe il primo risultato. Può essere utile considerare il valore $$FIRST come il numero di risultati che si desidera saltare prima di restituire i risultati.

Per assicurarti che i risultati siano impaginati correttamente, utilizza un parametro di ordinamento. Questo consente di restituire i risultati nello stesso ordine, in modo che l’impaginazione non si ripeta né salti i risultati. Ad esempio, per ordinare utilizzando l’ID oggetto, utilizza ID_Sort=asc.

Creazione di una regola di accesso

È possibile creare una regola di accesso per determinare chi può accedere a un oggetto. Di seguito sono riportati alcuni esempi di regole di accesso che è possibile impostare:

Per impostare un progetto in modo che venga condiviso solo con un utente con ID "abc123", utilizza la seguente richiesta:

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

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

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

Comportamento POST

POST inserisce un nuovo oggetto. La sintassi è identica a PUT, ma con alcune eccezioni. Poiché il nuovo oggetto non esiste ancora, non dispone di un ID. Per questo motivo, l’URI non include l’ID.

Creazione di un oggetto

Di seguito è riportato un esempio di richiesta di creazione di un nuovo progetto:

POST /attask/api/v15.0/project?name=Nuovo progetto

Copia di un oggetto

Alcuni oggetti supportano la copia. Per questi tipi di oggetto, è possibile creare nuovi oggetti pubblicandoli con un parametro copySourceID. Ad esempio, la richiesta seguente copia il progetto specificato e gli assegna un nuovo nome:

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

Caricamento di documenti

Puoi caricare i documenti tramite il seguente URL API:

POST/attask/api/v15.0/upload

{
    "handle": "4c7c08fa0000002ff924e298ee148df4"
}

POST /attask/api/v15.0/document?updates={
    nome: aFileName,
    handle: abc...123, (handle dal caricamento del file)
    docObjCode: PROJ, (o TASK, OPTASK, ecc.)
    objID: abc...123,
    currentVersion:{version:v1.0,fileName:aFileName}
}

Comportamento PUT

PUT viene utilizzato per aggiornare un oggetto esistente.

La risposta per un PUT è identica a un GET. In entrambi i casi, il server restituisce il nuovo stato dell'oggetto dopo l'aggiornamento. Tutte le regole utilizzate per modificare una risposta a una richiesta GET funzionano anche con PUT, ad esempio specificando campi aggiuntivi da restituire, dati personalizzati e così via.

Modifica di oggetti

Gli aggiornamenti agli oggetti vengono sempre eseguiti per ID utilizzando l’URI univoco dell’oggetto. I campi da aggiornare vengono specificati come parametri di richiesta. Ad esempio, per modificare il nome di un progetto puoi inviare una richiesta simile alla seguente:

PUT /attask/api/v15.0/project/4c7...?name=Nuovo nome progetto 
PUT /attask/api/v15.0/project?id=4c7...&name=Nuovo nome progetto

Specifica di modifiche JSON

Come mostrato nell’esempio seguente, è possibile utilizzare il parametro della richiesta updates per specificare i campi da aggiornare utilizzando la sintassi JSON:

PUT /attask/api/v15.0/project/4c7...?updates= Aggiornamenti 
{
     nome: "New Project Name", 
     stato: "CUR", 
     ... 
}

Esecuzione di aggiornamenti nidificati

Alcuni oggetti dispongono di raccolte private che possono essere aggiornate. Nell'esempio seguente viene illustrato come sovrascrivere le assegnazioni esistenti per una determinata attività:

PUT /attask/api/v15.0/task/4c7...?updates= Aggiornamenti 
{
    assegnazioni: [ 
        { 
            assignedToID: "2222...54d0, 
            assignmentPercent: 50,0 
        },{ 
            roleID: "1111...54d0"
        } 
    ] 
}
NOTE
Mentre gli aggiornamenti apportati al livello superiore sono di tipo sparso, gli aggiornamenti a un insieme o a un oggetto nidificato sostituiscono completamente l'insieme esistente. Per modificare una singola assegnazione su un'attività senza influire sugli oggetti, utilizzare PUT sull'assegnazione anziché sull'attività.

Nell'esempio seguente un progetto diventa una coda pubblica dell'helpdesk. Le proprietà della coda esistenti vengono sostituite.

PUT /attask/api/v15.0/project/4c7...?updates= Aggiornamenti 
{ 
    queueDef: { 
        isPublic: 1 
    } 
}

Utilizzo del parametro della richiesta di azione

Alcuni oggetti supportano azioni aggiuntive che possono essere eseguite in aggiunta a semplici modifiche. Puoi specificare queste azioni utilizzando il parametro della richiesta di azione. Ad esempio, la richiesta seguente ricalcola la sequenza temporale per un determinato progetto:

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

o

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

Spostamento di oggetti

Di seguito viene illustrata la sintassi per lo spostamento di un'attività da un progetto a un altro:

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

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

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

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

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

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

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

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

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

Di seguito è riportato un esempio di ciascun tipo di azione:

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

Condivisione di oggetti

L’esempio seguente illustra la sintassi per la condivisione di un progetto con un team:

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

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

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

Comportamento DELETE

DELETE rimuove un oggetto. In ogni caso, l’URI può includere il parametro force=true per fare in modo che il server rimuova i dati specificati e i relativi dipendenti. Nell'esempio seguente un'attività viene eliminata eseguendo il metodo HTTP DELETE su un 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

Aggiornamenti in blocco

Un’istruzione di aggiornamento in blocco aggiorna più oggetti contemporaneamente all’interno di una singola chiamata API. Una chiamata API per creazione in blocco viene generata in modo simile a una normale chiamata di aggiornamento, come mostrato negli esempi seguenti:

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

dati: [{
    ID: "53ff8d3d003b438b57a8a784df38f6b3",
    nome: "Test_Project_1",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priorità: 0,
    projectedCompletionDate: "2014-08-28T16:12:00:000-0400",
    stato: "CUR"
},
{
    ID: "53ff8d49003b43a2562aa34eea3b6b10",
    nome: "Test_Project_2",
    objCode: "PROJ",
    percentComplete: 0usi,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priorità: 0,
    projectedCompletionDate: "2014-08-28T16:12:00:000-0400",
    stato: "CUR"
}]

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

dati: [ {
     ID: "53ff8e15003b461d4560f7f65a440078",
     nome: "Test_Project_1_Edit",
     objCode: "PROJ",
     percentComplete: 0,
     plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
     plannedStartDate: "2014-08-28T11:00:00:000-0400",
     priorità: 0,
     projectedCompletionDate: "2014-08-28T16:16:00:000-0400",
     stato: "CUR"
},
{
    ID: "53ff8e19003b46238a58d303608de502"
    nome: "Test_Project_2_Edit",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priorità: 0,
    projectedCompletionDate: "2014-08-28T16:16:00:000-0400",
    stato: "CUR"
}]
NOTE
Le operazioni batch atomiche possono restituire solo "success: true" o un errore.
recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43