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.

OPMERKING
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" 
        } 
    ] 
OPMERKING
Wanneer het uitvoeren van een GET verzoek door uw browser adresbar, is het niet noodzakelijk om sessionID als deel van het verzoek te omvatten.

Er is speciale beveiliging toegevoegd rondom 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. In de volgende voorbeelden wordt getoond hoe dit op een DELETE-verzoek lijkt:

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

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.

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

Aanmelden

BELANGRIJK
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
OPMERKING
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 Van Bedrijfs Adobe Platform 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.

OPMERKING
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 in elke volgende GET-aanvraag te worden aangepast.

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

  5. Bericht het verstrekte antwoord.

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

GET-gedrag

Met de HTTP GET-methode kunt u een of meerdere objecten ophalen en rapporten uitvoeren.

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