DocumentatieWorkfrontHandleiding voor Workfront

Basisbeginselen van API

Last update: Wed Oct 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Onderwerpen:

Gemaakt voor:

  • Ontwikkelaar

Het doel voor de Adobe Workfront API is het vereenvoudigen van de integratie van gebouwen met Workfront door de introductie van een REST-ful architectuur die werkt via HTTP. In dit document wordt ervan uitgegaan dat u bekend bent met REST- en JSON-reacties en wordt de aanpak beschreven die door de Workfront API wordt gevolgd.

Een vertrouwdheid met het schema van Workfront zal u helpen bij het begrijpen van de gegevensbestandverhoudingen die kunnen worden gebruikt om gegevens uit Workfront voor integratiedoeleinden te trekken.

Grenswaarden en richtsnoeren

Voor consistente Workfront-systeemprestaties op aanvraag beperkt de Workfront API gelijktijdige API-threads. Deze handleiding voorkomt systeemproblemen die worden veroorzaakt door foutieve API-aanroepen. De Sandbox-omgeving heeft dezelfde gelijktijdige limiet voor de API-thread, waardoor klanten en partners API-aanroepen nauwkeurig kunnen testen voordat code wordt vrijgegeven voor productie.

Voor productie, voorproef, en testaandrijvingsmilieu's hebben de eindgebruikersverzoeken een maximumlengte van URI van 8892 bytes omdat zij door Workfront CDN (Akamai) worden verpletterd. Deze limiet geldt alleen voor URI's die worden gerouteerd via de CDN.

NOTE
deze limiet is niet van toepassing op sandboxomgevingen omdat sandboxomgevingen niet worden gerouteerd via de CDN.

Disclaimer

Elk gebruik van de API moet in de bètaomgeving van Workfront worden getest voordat het in de productieomgeving wordt uitgevoerd. Als een klant de API gebruikt voor een proces dat Workfront redelijkerwijs als belastend voor de software op aanvraag beschouwt (d.w.z. het proces veroorzaakt een wezenlijk negatief effect op de prestaties van de software voor andere klanten), behoudt Workfront zich het recht voor te vragen dat de klant dat proces beëindigt. Als de klant niet voldoet en het probleem zich blijft voordoen, behoudt Workfront zich het recht voor het proces te beëindigen.

Workfront API-URL

Voor informatie over URL die u zult gebruiken om Workfront API te roepen, zie formaat van het Domein voor Adobe Workfront API vraag.

Basisbeginselen van REST

In deze sectie wordt op hoog niveau uitgelegd hoe u kunt communiceren met de Workfront REST API voor de volgende REST-beginselen:

Object-URI

Elk object in het systeem krijgt een unieke URI die bestaat uit het objecttype en de id. In het volgende voorbeeld ziet u URI's die drie unieke objecten beschrijven:

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

Het objecttype is niet hoofdlettergevoelig en kan de afgekorte ObjCode (zoals proj) of de alternatieve objectnaam (project) zijn.

Zie voor een lijst met objecten, geldige ObjCodes en objectvelden  API Ontdekkingsreiziger.

NOTE
In de context van de Workfront API is een aangepast formulier een Category -object en een aangepast veld is een Parameter -object.

Bewerkingen

Objecten worden gemanipuleerd door een HTTP-aanvraag naar hun unieke URI te verzenden. De uit te voeren bewerking wordt opgegeven door de HTTP-methode.

De standaard HTTP-methoden komen overeen met de volgende bewerkingen:

  • GET - wint een voorwerp door identiteitskaart terug, zoekt naar alle voorwerpen door een vraag, looppas rapporten, of voert genoemde vragen uit
  • POST - neemt een nieuw voorwerp op
  • PUT - geeft een bestaand voorwerp uit
  • DELETE - schrapt een voorwerp

Om rond cliëntgebreken of protocollengtegrenzen te werken, kan de methodeparameter worden gebruikt om het gedrag van HTTP met voeten te treden. Een GET-bewerking kan bijvoorbeeld worden geïmplementeerd door de volgende URI te posten:

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

Antwoord

Elk verzoek krijgt een antwoord in JSON-indeling. De reactie heeft een gegevenskenmerk als de aanvraag succesvol was of een foutkenmerk als er een probleem was. De aanvraag

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

retourneert een JSON-respons die vergelijkbaar is met het volgende:


    "data": [
        
            "percentComplete": 0, 
            "status": "CUR", 
            "priority": 2, 
            "name": "Brand New Project", 
            "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
        } 
    ]
NOTE
Wanneer het uitvoeren van een verzoek van de GET door uw browser adresbar, is het niet noodzakelijk om sessionID als deel van het verzoek te omvatten.

De speciale veiligheid is toegevoegd rond PUT, POST, en DELETE verzoeken. Om het even welk verzoek dat in het schrijven aan of het schrappen van het gegevensbestand resulteert kan slechts worden uitgevoerd als sessionID=abc123 inbegrepen in URI is. De volgende voorbeelden tonen hoe dit op een verzoek van DELETE zou zoeken:

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

Verificatie

De API verifieert elke aanvraag om ervoor te zorgen dat de client toegang heeft om een aangevraagd object te bekijken of te wijzigen.

Verificatie wordt uitgevoerd door een sessie-id door te geven die kan worden gegeven met een van de volgende methoden:

Koptekstverificatie aanvragen

De aangewezen methode van authentificatie is een verzoekkopbal over te gaan genoemd SessionID die het zittingsteken bevat. Dit heeft het voordeel om tegen Cross-site van het Verzoek Smederij (CSRF)aanvallen veilig te zijn en zich niet met URI voor caching doeleinden te mengen.

Hieronder ziet u een voorbeeld van een aanvraagkoptekst:

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

Parameterverificatie aanvragen

U kunt verifiëren door een verzoekparameter genoemd sessionID over te gaan, zoals aangetoond in het volgende voorbeeld:

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

De API gebruikt de zelfde op koekje-gebaseerde authentificatie die door Web UI aan het systeem wordt gebruikt. Als een client zich aanmeldt bij Workfront via de webinterface, wordt voor alle AJAX aanroepen die vanuit dezelfde browser worden uitgevoerd, dezelfde verificatie gebruikt.

NOTE
Ter bescherming tegen de mogelijkheid van aanvallen CSRF (Cross-Site Request Svervalsing), is deze methode van authentificatie slechts beschikbaar voor read-only verrichtingen.

Aanmelden

IMPORTANT
Workfront raadt niet langer het gebruik van de /login eindpunt- of API-toetsen aan. Gebruik in plaats daarvan een van de volgende verificatiemethoden:
  • Serververificatie met JWT
  • Gebruikersverificatie met OAuth2
Voor instructies bij vestiging deze authentificatiemethodes, zie tot toepassingen OAuth2 voor de integratie van Workfront leiden
Voor instructies bij het gebruiken van serverauthentificatie in Workfront, zie vormen en gebruiken de douaneOAuth 2 van uw organisatie toepassingen gebruikend stroom JWT
Voor instructies bij het gebruiken van gebruikersauthentificatie in Workfront, zie vormen en gebruiken de douane OAuth 2 van uw organisatie toepassingen gebruikend de stroom van de vergunningscode
NOTE
De in dit gedeelte beschreven procedure is alleen van toepassing op organisaties die nog niet aan boord zijn gegaan bij het Adobe Business Platform. Aanmelden bij Workfront via de Workfront API is niet beschikbaar als uw organisatie is aangemeld bij het Adobe Business Platform.
Voor een lijst van procedures die verschillen gebaseerd op of uw organisatie aan het Bedrijfs Platform van de Adobe is genegeerd, zie Op platform-gebaseerde beleidsverschillen (Adobe Workfront/Adobe Bedrijfs Platform).

Met een geldige gebruikersnaam en wachtwoord kunt u de volgende aanvraag gebruiken om een sessie-id op te halen:

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

Dit plaatst een koekje om toekomstige verzoeken voor authentiek te verklaren evenals een reactie JSON met onlangs gecreeerde sessionID, de userID van de aangemelde gebruiker, en andere zittingsattributen terug te keren.

NOTE
Als u een aangewezen API-gebruiker hebt die ook beheerder is, wordt u door Workfront sterk aangeraden zich aan te melden met behulp van een API-sleutel.

producerend een Sleutel van API

U kunt een API-sleutel genereren wanneer u zich als die gebruiker bij het systeem aanmeldt, zoals in het volgende voorbeeld wordt getoond:

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

het terugwinnen van een eerder-Gegenereerde API Sleutel

U kunt ook een API-sleutel ophalen die eerder voor een bepaalde gebruiker is gegenereerd door getApiKey uit te voeren:

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

Vervolgens kunt u dit resultaat gebruiken om elke API-aanroep te verifiëren door "apiKey" als een parameter request met deze waarde toe te voegen in plaats van een sessionID of gebruikersnaam en wachtwoord. Dit is uit veiligheidsoogpunt gunstig.

Het volgende verzoek is een voorbeeld van het ophalen van gegevens van een project met behulp van apiKey:

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

Het ongeldig maken van een API Sleutel

Als de apiKey-waarde is gecompromitteerd, kunt u "clearApiKey" uitvoeren, waarmee de huidige API-sleutel ongeldig wordt gemaakt, zoals in het volgende voorbeeld wordt getoond:

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

Als de API is gewist, kunt u getApiKey opnieuw uitvoeren om een nieuwe API-sleutel te genereren.

Afmelden

Wanneer een zitting volledig is, kunt u het volgende verzoek gebruiken om de gebruiker uit te loggen, verhinderend om het even welke verdere toegang met sessionID.

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

De sessionID die moet worden geregistreerd kan of als koekje, verzoekkopbal, of verzoekparameter worden gespecificeerd.

Een gebruiker afmelden:

  1. Navigeer naar het aanmeldingsscherm, maar meld u niet aan.

  2. Wijzig de URL in /attask/api/v15.0/project/search.
    De pagina kan niet worden gevonden.

  3. Vervang het woord onderzoek met login?username=admin&password=user, substituerend uw gebruikersbenaming en wachtwoord voor admin en *user
    *Deze sessie wordt in de browser opgeslagen als een cookie en hoeft niet opnieuw te worden vermeld in elke volgende GET-aanvraag.

  4. Wijzig de URL weer in /attask/api/v15.0/project/search .

  5. Bericht het verstrekte antwoord.

U moet altijd sessionID omvatten die na login wordt verstrekt wanneer het uitvoeren van PUT, POST, en DELETE verzoeken.

Gedrag van GET

Gebruik de HTTP-methode om een of meerdere objecten op te halen en rapporten uit te voeren.

Objecten ophalen

U kunt een zoekopdracht naar objecten verbeteren met wijzigingstoetsen en filters.

Een object ophalen met de object-id

Als u de id van een object kent, kunt u het object ophalen door de unieke URI van het object te openen. De aanvraag

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

retourneert een reactie die lijkt op het volgende:


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

U kunt veelvoudige voorwerpen in het zelfde verzoek terugwinnen door de parameter van het identiteitskaart- verzoek te specificeren en een komma-gescheiden lijst van identiteitskaart's te geven, zoals aangetoond in het volgende voorbeeld:

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

Let op: de aanvraag /attask/api/v15.0/project?id=… is gelijk aan de aanvraag /attask/api/v15.0/project/... .

Een object ophalen met de URI

Als u een object wilt ophalen op andere criteria dan de id, kunt u zoeken naar de URI.

U kunt bijvoorbeeld het volgende verzoek gebruiken om een lijst met alle projecten in het systeem te retourneren:

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

U kunt filters specificeren gebruikend de verzoekparameters als naam-waardeparen. In het volgende voorbeeld wordt bijvoorbeeld een aanvraag getoond waarin alle huidige projecten worden gevonden:

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

Het volgende verzoek vindt alle taken die nog niet volledig zijn en die aan een gebruiker genoemd John worden toegewezen.

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

Zoekopties gebruiken

De volgende tabel bevat een aantal opties die u kunt gebruiken met de Workfront API.

Modifier
Beschrijving
Voorbeeld
eq
retourneert resultaten die de status van gesloten hebben
…status=cls&status_Mod=eq…
ne
retourneert resultaten die niet de status van closed hebben
…status=cls&status_Mod=ne…
gist
retourneert resultaten met een percentage voltooid groter dan of gelijk aan 50
…percentComplete=50&percentComplete_Mod=gte…
lte
retourneert resultaten die een percentage voltooid hebben van minder dan of gelijk aan 50
…percentComplete=50&percentComplete_Mod=lte…
isnull
retourneert resultaten als de beschrijving Null is
…description_Mod=is null…
notnull
retourneert resultaten als de beschrijving niet null is
…description_Mod=notnull…
contains
retourneert resultaten als de naam "Workfront" bevat
…name=Workfront&name_Mod=contains…
Tussen
retourneert resultaten die de laatste 7 dagen een ingangsdatum hebben
…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…
NOTE
Zoekverzoeken zijn hoofdlettergevoelig. Als er een fout optreedt, controleert u of   _Mod en _Range hebben de correcte kapitalisatie.

OR-instructies gebruiken

U kunt een zoekopdracht verfraaien door een parameter toe te voegen die "OR" bevat, en een getal om het niveau van een filter of reeks filters aan te geven.

Een OF verklaring keert slechts verslagen in de API vraag terug die aan de OF verklaring het filtreren criteria voldoen. Filters worden niet geïmpliceerd over OR verklaringsniveaus.

Als u bijvoorbeeld wilt filteren op

  • Taken die een naam hebben die "Planning"OF bevatten
  • Taken in een portfolio met de naam "FixedAssets" EN toegewezen aan iemand met de naam "Steve" OR
  • Taken die een oudertaak hebben genoemd "Definitieve Taak"

Gebruik vervolgens de volgende API-aanroep met de verschillende OR-instructies:

GET /attask/api/v15.0/task/search?name=Planning 
&name_Mod=contains 
 &OR :1: portefeuille:name=FixedAssets 
 & OF :1: portefeuille:name_Mod=eq 
&OR :1: toegewezenAan:name=Steve 
 & OF :1: toegewezenAan:name_Mod=icontains 
 &OF :2: ouder:name=Final Taak 
 &OF :2: ouder:name_Mod=eq

Filterparameters gebruiken

Een mogelijk probleem bij het gebruik van URL-parameters voor zoekfilters is dat Workfront bepaalde parameters parseert voordat er op verschillende verificatiemethoden wordt gecontroleerd (bijvoorbeeld gebruikersnaam, wachtwoord, apiKey, cookie). Wanneer dit gebeurt worden de parameters niet gebruikt als filters in de vraag.

U voorkomt dit probleem door deze waarden in filterparameters met JSON-opmaak te plaatsen. Als u bijvoorbeeld wilt filteren op de gebruiker van de gebruikersnaam in plaats van deze te gebruiken

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

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

De parameter Kaartverzoek gebruiken

Standaard zijn de gegevens die door een zoekopdracht worden geretourneerd, een JSON-array. Afhankelijk van uw gebruikscase kan het efficiënter zijn om het resultaat op te halen als een JSON-object dat met ID wordt geïndexeerd. Dit kan worden gedaan door de parameter van het kaartverzoek te gebruiken. De aanvraag

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


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

De veldverzoekparameter gebruiken

Als u een object ophaalt, wordt standaard alleen de meest gebruikte subset met velden geretourneerd.

U kunt de parameter van het gebiedsverzoek gebruiken om een komma-gescheiden lijst van specifieke gebieden te specificeren is teruggekeerd. De aanvraag

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


    "priority": 2, 
    "name": "first task", 
    "ID": "4c7c08fa000002ff924e298ee148df4", 
    "SchedulStartDate": "2010-08-30T09 :00: 00:000-0600"
NOTE
Deze veldnamen zijn hoofdlettergevoelig.

Voor een lijst met mogelijke veldverwijzingen raadpleegt u de  API Ontdekkingsreiziger

Zoeken naar geneste objecten

U kunt zoeken naar geneste objecten. Standaard worden geneste objecten alleen met de naam en id geretourneerd. Als u bijvoorbeeld alle problemen samen met de eigenaar wilt ophalen, gebruikt u de volgende aanvraag:

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

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


    "name": "an major issue", 
    "ID": "4c78285f00000908ea8cfd66e084939f", 
    "owner": 
        "title": "Operations Specialist", 
        "phoneNumber": "555-1234", 
        "name": "Admin User", 
        "ID": "4c76ed7a000054c172b2c2d9f7f81c3" 
    }

Geneste verzamelingen ophalen

U kunt geneste verzamelingen van objecten ophalen. Als u bijvoorbeeld een project wilt ophalen met alle bijbehorende taken, gebruikt u de volgende aanvraag:

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

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

Zoeken naar meerdere geneste velden

Standaard worden alleen de naam en de id van elke taak geretourneerd, maar u kunt aanvullende geneste velden opgeven met een dubbele puntnotatie. Als u alle beschikbare velden voor een verwant object of verzameling wilt weergeven, voegt u gewoon een dubbele punt en sterretje toe aan de verwijzing naar object of verzameling.

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

Aangepaste gegevens ophalen

U kunt aangepaste gegevensvelden ophalen met het voorvoegsel "DE:". Als u bijvoorbeeld een project wilt aanvragen met de parameter "CustomText", gebruikt u de volgende aanvraag:

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


    "name": "custom data project", 
    "ID": "4c9a954f000001afad0687d7b1b4e43", 
    "DE:CustomText": "task b" 

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


    "name": "custom data project", 
    "ID": "4c9a954f000001afad0687d7b1b4e43", 
    parameterValues: 
        "DE:CustomText": "task b", 
        "DE:CustomNumber": 1.4, 
        "DE:CustomCheckBox": ["first", "second", "third"] 
    }

Benoemde query's gebruiken

Sommige objecttypen hebben benoemde zoekopdrachten die doorgaans worden uitgevoerd en die beschikbaar zijn door de naam van de query aan het einde van het objecttype URI toe te voegen. Met de volgende aanvraag worden bijvoorbeeld de werkitems (taken en problemen) opgehaald waaraan de gebruiker momenteel is toegewezen:

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

Count gebruiken

Met count kunt u het aantal resultaten retourneren dat overeenkomt met uw query. Dit kan handig zijn wanneer u de gegevens in de resultaten niet nodig hebt. Door alleen het aantal te retourneren, kan de server de aanvraag sneller verwerken en bandbreedte opslaan. De aanvraag

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


    "count": 3

Een rapport aanvragen

U kunt een rapportverzoek uitvoeren, waar slechts het totaal van één of ander gebied met één of meerdere groeperingen wordt gewenst. Zoals in het volgende voorbeeld wordt getoond, is de rapportsyntaxis gelijk aan de syntaxis voor de SOAP API:

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


    "First Project": 
        "sum_hours": 15 
    }, 
     "Second Project": 
        "sum_hours": 30 
    } 


    "First Project": 
        "sum_hours": 15 
    }, 
    "Second Project": 
        "sum_hours": 30 
    }, 
    "$$ROLLUP": 
        "sum_hours": 45 
    }

Zoekresultaten sorteren in de API

U kunt de resultaten op elk veld sorteren als u het volgende aan uw API-aanroep toevoegt:

&entryDate_Sort=asc

Als u bijvoorbeeld wilt sorteren op geplande begindatum van taak, verwijdert u entryDate en vervangt u deze door scheduledCompletionDate.

Dit werkt voor de meeste velden in Workfront.

Zoekbeperkingen overwegen

Bij het opvragen van een object moet speciale aandacht worden besteed aan de relatie tussen verwante objecten en zoekbeperkingen. Bijvoorbeeld, zoals aangetoond in de volgende lijst, kan een vraag voor projecten niet meer dan 2.000 projecten terugkeren. Deze 2000 projecten worden beschouwd als "primaire objecten". Als u voor het gebied van Taken op de projecten vraagt, wordt het gebied van Taken, dat een inzameling is, een secundair voorwerp aan het primaire objectenProject. Een vraag voor het gebied van Taken kan duizenden taken op projecten omvatten. In totaal kan het gecombineerde aantal geretourneerde objecten (projecten en taken) het maximum van 50.000 niet overschrijden.

Om optimale prestaties te verzekeren, toont de volgende lijst de beperkingen die op onderzoeksverzoeken worden geplaatst.

Zoekresultaat
Beperking
Beschrijving
Standaardaantal resultaten
100
Als er geen limiet is opgegeven in het queryfilter (d.w.z. $$LIMIT), mag het resultaat niet meer dan 100 primaire objecten bevatten.
zie Gebruikend Gepagineerde Reactiesvoor instructies op hoe te om deze beperking met voeten te treden.
Max. aantal resultaten
2.000
Het queryfilter (d.w.z. $$LIMIT) kan maximaal 2000 resultaten retourneren. Zie "Gepagineerde reacties" voor meer informatie.
Maximale velddiepte
4
Bij het identificeren van de velden die u wilt weergeven, kunt u niet meer dan vier niveaus van het object dat wordt gevraagd, weggaan.
Max. aantal objecten
50.000
De resultaatset mag geen 50000 primaire en secundaire objecten bevatten.
Max. aantal velden
1.000.000
Als de resultaatset minder dan 50000 objecten is, kunnen de resultaten maximaal 1000.000 velden bevatten.
Max. aantal batch-inhoud maakt/werkt bij
100
De maximale limiet voor het maken of bijwerken van batch is 100.

Gepagineerde reacties gebruiken using-paginated-responses

Als u de standaardlimiet voor zoekopdrachten met betrekking tot het aantal resultaten wilt overschrijven en 200 resultaten wilt toestaan, kunt u het filter $$LIMIT=200 in de query opnemen, zoals in het volgende voorbeeld wordt getoond:

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

Om betrouwbaarheid en prestaties voor andere huurders in het systeem te verzekeren, is de maximum toegestane resultaatgrens per vraag 2000 voorwerpen. Als u probeert een grotere limiet op te geven, wordt een IllegalArgumentException -foutbericht weergegeven.

Daarom adviseren wij u het gebruiken van gepagineerde reacties voor grote datasets overweegt. Voeg het filter $$FIRST toe om het eerste resultaat op te geven dat moet worden geretourneerd. Bijvoorbeeld, keert het volgende verzoek resultaten 201-250 voor een vraag terug:

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

In het bovenstaande voorbeeld retourneert $$FIRST=200 het 201e resultaat. $$FIRST=0 retourneert het eerste resultaat. Het kan helpen om van de waarde $$FIRST als aantal resultaten te denken u wilt overslaan alvorens resultaten terug te keren.

Gebruik een sorteerparameter om ervoor te zorgen dat de resultaten correct worden gepagineerd. Hierdoor kunnen de resultaten in dezelfde volgorde worden geretourneerd, zodat de paginering de resultaten niet herhaalt of overslaat. Als u bijvoorbeeld wilt sorteren met de object-id, gebruikt u ID_Sort=asc .

Toegangsregels maken

U kunt een toegangsregel maken om te bepalen wie toegang heeft tot een object. Hieronder volgen voorbeelden van toegangsregels die u kunt instellen:

Om een project te plaatsen zodat wordt het gedeeld slechts met een gebruiker met identiteitskaart "abc123"gebruik het volgende verzoek:

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

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

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

Gedrag van POST

POST voegt een nieuw object in. De syntaxis is identiek aan PUT, maar met een paar uitzonderingen. Omdat het nieuwe object nog niet bestaat, heeft het geen id. Daarom bevat de URI de id niet.

Een object maken

Hieronder ziet u een voorbeeld van een aanvraag om een nieuw project te maken:

POST /attask/api/v15.0/project?name=New Project

Een object kopiëren

Sommige objecten ondersteunen kopiëren. Voor deze objecttypen is het mogelijk om nieuwe objecten te maken door te posten met een copySourceID-parameter. Met de volgende aanvraag wordt bijvoorbeeld het opgegeven project gekopieerd en krijgt het een nieuwe naam:

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

Documenten uploaden

U kunt documenten uploaden via de volgende API-URL:

POST /attask/api/v15.0/upload


    "handle": "4c7c08fa000002ff924e298ee148df4"

POST /attask/api/v15.0/document?updates={
    name: aFileName,
    handle: abc...123, (handle from the file upload) 
    docObjCode: PROJ, (of TASK, OPTASK, enz.) 
    objID: abc...123,
    currentVersion:{version:v1.0,fileName:aFileName}

Gedrag van PUT

PUT wordt gebruikt om een bestaand object bij te werken.

De reactie voor een PUT is identiek aan een GET. In beide gevallen retourneert de server de nieuwe status van het object na de update. Alle regels die worden gebruikt om een reactie op een verzoek van de GET te veranderen werken ook met PUT, zoals het specificeren van extra te teruggekeerde gebieden, douanegegevens, etc.

Objecten bewerken

Objecten worden altijd bijgewerkt door de id met behulp van de unieke URI van het object. Velden die moeten worden bijgewerkt, worden opgegeven als aanvraagparameters. Als u bijvoorbeeld de naam van een project wilt wijzigen, kunt u een aanvraag verzenden die vergelijkbaar is met het volgende:

PUT /attask/api/v15.0/project/4c7...?name=New Project Name 
 PUT /attask/api/v15.0/project?id=4c7..&name=New Project Name

JSON-bewerkingen opgeven

Zoals in het volgende voorbeeld wordt getoond, kunt u de parameter van het updateverzoek gebruiken om de gebieden te specificeren die moeten worden bijgewerkt gebruikend syntaxis JSON:

PUT /attask/api/v15.0/project/4c7...?updates= 
{
     name: "New Project Name", 
     status: "CUR", 
     ...

Geneste updates maken

Sommige objecten hebben privéverzamelingen die kunnen worden bijgewerkt. In het volgende voorbeeld ziet u hoe u de bestaande toewijzingen voor een bepaalde taak overschrijft:

PUT /attask/api/v15.0/task/4c7...?updates= 
{
    toewijzingen: [ 
        
            assignedToID: "2222...54d0, 
            assignPercent: 50.0 
        },{ 
            roleID: "1111...54d0"
        } 
    ]
NOTE
Terwijl de updates aan het hoogste niveau worden gemaakt klein zijn, vervangen de updates aan een inzameling of een genesteld voorwerp volledig de bestaande inzameling. Als u één toewijzing op een taak wilt bewerken zonder de objecten te beïnvloeden, gebruikt u PUT op de toewijzing in plaats van op de taak.

In het volgende voorbeeld wordt van een project een wachtrij voor een openbare helpdesk gemaakt. De bestaande wachtrijeigenschappen worden vervangen.

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

De parameter Handelingverzoek gebruiken

Sommige objecten ondersteunen aanvullende acties die naast eenvoudige bewerkingen kunnen worden uitgevoerd. U kunt deze handelingen opgeven met de parameter voor actiedracht. In het volgende verzoek wordt bijvoorbeeld de tijdlijn voor een bepaald project opnieuw berekend:

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

 of 

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

Objecten verplaatsen

In het volgende voorbeeld ziet u de syntaxis voor het verplaatsen van een taak van het ene project naar het andere:

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

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

 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/retrieveApproval 

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

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

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

Hieronder ziet u een voorbeeld van elk actietype:

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

Objecten delen

In het volgende voorbeeld ziet u de syntaxis voor het delen van een project met een team:

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

PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxx?method=PUT&updates={accessRules:[{accessorID:'123abcxxxxxxxxxxxxxxxxxxxx',accessorObjCode:'TEAMOB',xxcore Handeling:'VIEW'}]}

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

DELETE-gedrag

DELETE verwijdert een object. In elk geval, kan URI de parameter force=true omvatten om de server te veroorzaken om de gespecificeerde gegevens en zijn afhankelijke personen te verwijderen. In het volgende voorbeeld wordt een taak verwijderd door de HTTP DELETE-methode uit te voeren op een URI:

DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0 
 DELETE /attask/api/v15.0/task?id=4c7822 1c0000d6fa8d5e52f07a1d54d0 
 DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d5 4d0?force=true 
 DELETE /attask/api/v15.0/task?id=4c78821c000d6fa8d5e52f07a1d54d0?force=true

Bulkupdates

Met een bulkupdateinstructie worden meerdere objecten tegelijkertijd bijgewerkt binnen één API-aanroep. Een bulk creeert API vraag wordt gebouwd gelijkaardig aan een normale updatevraag, zoals aangetoond in de volgende voorbeelden:

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

gegevens: [
    ID: "53ff8d3d003b438b57a8a784df38f6b3", 
    name: "Test_Project_1", 
    objCode: "PROJ", 
    percentComplete: 0, 
    scheduledCompletionDate: "2014-08-28T11 :00: 00:000-0400", 
    SchedulStartDate: "2014-08-28T11 :00: 00:000-0400", 
    prioriteit: 0, 
    projectedCompletionDate: "2014-08-28T16 :12: 00:000-0400", 
    status: "CUR"
, 
 {
    ID: "53ff8d49003b43a2562aa34eea3b6b10", 
    name: "Test_Project_2", 
    objCode: "PROJ", 
    percentComplete: 0usi,
    scheduledCompletionDate: "2014-08-28T11 :00: 00:000-0400", 
    scheduledStartDate: "2014-08-28T11 :00: 00:000-0400", 
    priority: 0, 
    projectedCompletionDate: "2014-08-28T16 :12: 00:000-0400", 
    status: "CUR"
]

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

gegevens: [
     ID: "53ff8e15003b461d4560f7f65a440078", 
     name: "Test_Project_1_Edit", 
     objCode: "PROJ", 
     percentComplete: 0, 
     scheduledCompletionDate: "2014-08-28T11 :00: 00:000-0400", 
     SchedulStartDate: "2014-08-28T11 :00: 00:000-0400", 
     prioriteit: 0, 
     projectedCompletionDate: "2014-08-28T16 :16: 00:000-0400", 
     status: "CUR"
, 
 {
    ID: "53ff8e19003b46238a58d303608de502", 
    name: "Test_Project_2_Edit", 
    objCode: "PROJ", 
    percentComplete: 0, 
    scheduledCompletionDate: "2014-08-28T11 :00: 00:000-0400", 
    scheduledStartDate: "2014-08-28T11 :00: 00:000-0400", 
    priority: 0, 
    projectedCompletionDate: "2014-08-28T16 :16: 00:000-0400", 
    status: "CUR"
]
NOTE
Atoombatchbewerkingen kunnen alleen 'success: true' of een fout retourneren.
recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43