API-Grundlagen
Ziel der Adobe Workfront-API ist es, die Erstellung von Integrationen mit Workfront zu vereinfachen, indem eine REST-fähige Architektur eingeführt wird, die über HTTP ausgeführt wird. In diesem Dokument wird davon ausgegangen, dass Sie mit REST- und JSON-Antworten vertraut sind und den Ansatz der Workfront-API beschrieben.
Eine Kenntnis des Workfront-Schemas hilft Ihnen dabei, die Datenbankbeziehungen zu verstehen, die zum Abrufen von Daten aus Workfront für Integrationszwecke genutzt werden können.
Einschränkungen und Richtlinien
Um eine konsistente On-Demand-Systemleistung von Workfront sicherzustellen, beschränkt die Workfront-API gleichzeitige API-Threads. Diese Schutzmaßnahme verhindert Systemprobleme, die durch missbräuchliche API-Aufrufe verursacht werden. In der Sandbox-Umgebung gibt es dieselbe Grenze für gleichzeitige API-Threads, die es Kunden und Partnern ermöglicht, API-Aufrufe genau zu testen, bevor Code für die Produktion freigegeben wird.
Für Produktions-, Vorschau- und Testumgebungen haben Endbenutzeranforderungen eine maximale URI-Länge von 8892 Byte, da sie über das Workfront CDN (Akamai) weitergeleitet werden. Diese Beschränkung gilt nur für URIs, die über das CDN weitergeleitet werden.
Haftungsausschluss
Jede Verwendung der API sollte in der Workfront Beta-Umgebung getestet werden, bevor sie in der Produktionsumgebung ausgeführt wird. Wenn ein Kunde die API für einen Prozess verwendet, der nach vernünftigem Ermessen für Workfront mit der On-Demand-Software belastend ist (d. h., der Prozess verursacht wesentliche negative Auswirkungen auf die Leistung der Software für andere Kunden), behält sich Workfront das Recht vor, vom Kunden die Beendigung dieses Prozesses zu verlangen. Wenn der Kunde nicht einhält und das Problem weiterhin besteht, behält sich Workfront das Recht vor, den Prozess zu beenden.
Workfront API-URL
Informationen über die URL, die Sie zum Aufrufen der Workfront-API verwenden werden, finden Sie unter Domänenformat für Adobe Workfront-API-Aufrufe.
REST-Grundlagen
In diesem Abschnitt erhalten Sie eine allgemeine Einführung in die Interaktion mit der Workfront REST-API für die folgenden REST-Grundsätze:
Objekt-URI
Jedes Objekt im System erhält einen eindeutigen URI, der aus dem Objekttyp und der ID besteht. Die folgenden Beispiele zeigen URIs, die drei eindeutige Objekte beschreiben:
/attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
/attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d1
/attask/api/v15.0/issue/4c78821c0000d6fa8d5e52f07a1d54d2
Beim Objekttyp wird nicht zwischen Groß- und Kleinschreibung unterschieden. Hierbei kann es sich entweder um den abgekürzten ObjCode (z. B. proj) oder den alternativen Objektnamen (project) handeln.
Eine Liste der gültigen ObjCodes finden Sie unter API-Explorer.
Vorgänge
Objekte werden bearbeitet, indem eine HTTP-Anfrage an ihren eindeutigen URI gesendet wird. Der auszuführende Vorgang wird durch die HTTP-Methode angegeben.
Die standardmäßigen HTTP-Methoden entsprechen den folgenden Vorgängen:
- GET - Ruft ein Objekt nach ID ab, sucht mithilfe einer Abfrage nach allen Objekten, führt Berichte aus oder führt benannte Abfragen aus.
- POST - Fügt ein neues Objekt ein
- PUT - Bearbeiten eines vorhandenen Objekts
- DELETE - Löscht ein Objekt
Um Client-Mängel oder Beschränkungen der Protokolllänge zu umgehen, kann der Methodenparameter verwendet werden, um das HTTP-Verhalten zu überschreiben. Beispielsweise kann ein GET-Vorgang durch Posten des folgenden URI implementiert werden:
GET /attask/api/v15.0/project?id=4c78...54d0&method=get
GET /attask/api/v15.0/project/4c78...54d0?method=get
Reaktion
Jede Anfrage erhält eine Antwort im JSON-Format. Die Antwort verfügt entweder über ein Datenattribut, wenn die Anfrage erfolgreich war, oder über ein Fehlerattribut, wenn ein Problem aufgetreten ist. Beispielsweise die Anfrage
GET /attask/api/v15.0/proj/4c7c08b20000002de5ca1ebc19edf2d5
gibt eine JSON-Antwort zurück, die der folgenden ähnelt:
{
"data": [
{
"percentComplete": 0,
"status": "CUR",
"priority": 2,
"name": "Brand New Project",
"ID": "4c7c08b20000002de5ca1ebc19edf2d5"
}
]
Besondere Sicherheit wurde für PUT-, POST- und DELETE-Anfragen hinzugefügt. Eine Anforderung, die dazu führt, dass in die Datenbank geschrieben oder daraus gelöscht wird, kann nur ausgeführt werden, wenn der URI den Wert sessionID=abc123 enthält. Die folgenden Beispiele zeigen, wie dies nach einer DELETE-Anfrage suchen würde:
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
Authentifizierung
Die API authentifiziert jede Anfrage, um sicherzustellen, dass der Client Zugriff auf das Anzeigen oder Ändern eines angeforderten Objekts hat.
Die Authentifizierung erfolgt durch Übergabe einer Sitzungs-ID, die mit einer der folgenden Methoden angegeben werden kann:
Authentifizierung des Anforderungsheaders
Die bevorzugte Authentifizierungsmethode besteht darin, einen Anforderungsheader namens SessionID zu übergeben, der das Sitzungstoken enthält. Dies hat den Vorteil, dass sie vor Cross-Site Request Forgery (CSRF) -Angriffen geschützt sind und den URI nicht zum Zwischenspeichern stören.
Im Folgenden finden Sie ein Beispiel für eine Anfrage-Kopfzeile:
GET /attask/api/v15.0/project/search
SessionID: abc1234
Authentifizierung von Anfrageparametern
Sie können sich authentifizieren, indem Sie einen Anforderungsparameter namens sessionID übergeben, wie im folgenden Beispiel gezeigt:
GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0?sessionID=abc1234
Cookie-basierte Authentifizierung
Die API verwendet dieselbe Cookie-basierte Authentifizierung, die von der Web-Benutzeroberfläche für das System verwendet wird. Wenn sich ein Client über die Web-Benutzeroberfläche bei Workfront anmeldet, verwenden alle AJAX Aufrufe, die innerhalb desselben Browsers durchgeführt werden, dieselbe Authentifizierung.
Anmeldung
/login
-Endpunkts oder der API-Schlüssel. Verwenden Sie stattdessen eine der folgenden Authentifizierungsmethoden:- Serverauthentifizierung mit JWT
- Benutzerauthentifizierung mit OAuth2
Mit einem gültigen Benutzernamen und Kennwort können Sie die folgende Anfrage verwenden, um eine Sitzungs-ID zu erhalten:
POST /attask/api/v15.0/login?username=admin&password=user
Dadurch wird ein Cookie gesetzt, um zukünftige Anforderungen zu authentifizieren und eine JSON-Antwort mit der neu erstellten sessionID, der Benutzer-ID des angemeldeten Benutzers und anderen Sitzungsattributen zurückzugeben.
Generieren eines API-Schlüssels
Sie können einen API-Schlüssel generieren, wenn Sie sich als dieser Benutzer beim System anmelden, wie im folgenden Beispiel gezeigt:
PUT /attask/api/v15.0/user?action=generateApiKey&username= username&password=password&method=put
Abrufen eines zuvor generierten API-Schlüssels
Sie können auch einen API-Schlüssel abrufen, der zuvor für einen bestimmten Benutzer generiert wurde, indem Sie getApiKey ausführen:
PUT /attask/api/v15.0/user?action=getApiKey&username=user@email.com&password=userspassword&method=put
Anschließend können Sie dieses Ergebnis verwenden, um jeden API-Aufruf zu authentifizieren, indem Sie "apiKey"als Anforderungsparameter mit diesem Wert anstelle einer sessionID oder eines Benutzernamen und Kennworts hinzufügen. Aus sicherheitspolitischer Sicht ist dies von Vorteil.
Die folgende Anfrage ist ein Beispiel für das Abrufen von Daten aus einem Projekt mithilfe des apiKey:
GET /attask/api/v15.0/project/abc123xxxxx?apiKey=123abcxxxxxxxxx
Invalidierung eines API-Schlüssels
Wenn der apiKey -Wert kompromittiert wurde, können Sie "clearApiKey"ausführen, der den aktuellen API-Schlüssel ungültig macht, wie im folgenden Beispiel gezeigt:
GET /attask/api/v15.0/user?action=clearApiKey&username=user@email.com&password=userspassword&method=put
Nach der Löschung können Sie getApiKey erneut ausführen, um einen neuen API-Schlüssel zu generieren.
Abmelden
Wenn eine Sitzung abgeschlossen ist, können Sie die folgende Anfrage verwenden, um den Benutzer abzumelden, wodurch jeder weitere Zugriff mit der sessionID verhindert wird.
GET /attask/api/v15.0/logout?sessionID=abc1234
Die abgemeldete sessionID kann entweder als Cookie, Anfragekopfzeile oder Anfrageparameter angegeben werden.
So melden Sie einen Benutzer ab:
-
Navigieren Sie zu Ihrem Anmeldebildschirm, melden Sie sich jedoch nicht an.
-
Ändern Sie die URL in /attask/api/v15.0/project/search.
Beachten Sie, dass die Seite nicht gefunden wird. -
Ersetzen Sie das Wort search durch login?username=admin&password=user, indem Sie Ihren Benutzernamen und Ihr Kennwort für admin und *user ersetzen.
*Diese Sitzung wird im Browser als Cookie gespeichert und muss nicht bei jeder nachfolgenden GET-Anfrage neu angegeben werden. -
Ändern Sie die URL zurück zu "/attask/api/v15.0/project/search".
-
Beachten Sie die Antwort.
Sie müssen bei der Ausführung von PUT-, POST- und DELETE-Anfragen immer die sessionID angeben, die nach der Anmeldung angegeben wurde.
Verhalten der GET
Verwenden Sie die HTTP-GET-Methode, um ein Objekt oder mehrere Objekte abzurufen und Berichte auszuführen.
Abrufen von Objekten
Sie können die Suche nach Objekten mithilfe von Modifikatoren und Filtern optimieren.
Abrufen eines Objekts mit der Objekt-ID
Wenn Sie die ID eines Objekts kennen, können Sie das Objekt abrufen, indem Sie auf seinen eindeutigen URI zugreifen. Beispielsweise die Anfrage
GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
gibt eine Antwort ähnlich der folgenden zurück:
{
"percentComplete": 0,
"status": "CUR",
"priority": 2,
"name": "Brand New Project",
"ID": "4c7c08b20000002de5ca1ebc19edf2d5"
Sie können mehrere Objekte in derselben Anforderung abrufen, indem Sie den Parameter für die ID-Anforderung angeben und eine kommagetrennte Liste von IDs angeben, wie im folgenden Beispiel gezeigt:
GET /attask/api/v15.0/project?id=4c78...54d0,4c78...54d1
Beachten Sie, dass die Anforderung /attask/api/v15.0/project?id=… mit der Anforderung /attask/api/v15.0/project/...
übereinstimmt.
Abrufen eines Objekts mit dem URI
Wenn Sie ein Objekt anhand anderer Kriterien als der ID abrufen möchten, können Sie nach dem URI suchen.
Beispielsweise können Sie die folgende Anfrage verwenden, um eine Liste aller Projekte im System zurückzugeben:
GET /attask/api/v15.0/project/search
Sie können Filter mithilfe der Anforderungsparameter als Name-Wert-Paare angeben. Im folgenden Beispiel sehen Sie eine Anfrage, die alle aktuellen Projekte finden würde:
GET /attask/api/v15.0/project/search?status=CUR
Die folgende Anfrage sucht alle Aufgaben, die noch nicht abgeschlossen sind und die einem Benutzer mit dem Namen John zugewiesen sind.
GET /attask/api/v15.0/task/search?percentComplete=100
&percentComplete_Mod=lt &assignedTo:firstName=John
Verwenden von Suchmodifikatoren
In der folgenden Tabelle sind einige der Modifikatoren aufgeführt, die Sie mit der Workfront-API verwenden können.
…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=contains…
…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…
Verwenden von ODER-Anweisungen
Sie können die Suche verbessern, indem Sie einen Parameter hinzufügen, der "OR"enthält, sowie eine Zahl, die die Ebene eines Filters oder einer Reihe von Filtern angibt.
Eine OR-Anweisung gibt nur Datensätze im API-Aufruf zurück, die den Filterkriterien der OR-Anweisung entsprechen. Filter werden nicht über OR-Anweisungsebenen hinweg impliziert.
Wenn Sie beispielsweise nach
- Aufgaben mit einem Namen, der "Planning"OR enthält
- Aufgaben in einem Portfolio mit dem Namen "FixedAssets"UND zugewiesen an eine Person mit dem Namen "Steve"ODER
- Aufgaben mit einer übergeordneten Aufgabe namens "Final Task"
verwenden Sie dann den folgenden API-Aufruf mit mehreren ODER-Anweisungen:
GET /attask/api/v15.0/task/search?name=Planning
&name_Mod=contains
&OR:1:portfolio:name=FixedAssets
&OR:1:portfolio:name_Mod=eq
&OR:1:assignedTo:name=Steve
&OR:1:assignedTo:name_Mod=cid contains
&OR:2:parent:name=Final Task
&OR:2:parent:name_Mod=eq
Filterparameter verwenden
Ein potenzieller Fehler bei der Verwendung von URL-Parametern für Suchfilter besteht darin, dass Workfront bestimmte Parameter analysiert, bevor nach verschiedenen Authentifizierungsmethoden gesucht wird (z. B. Benutzername, Kennwort, apiKey, Cookie). In diesem Fall werden die Parameter nicht als Filter im Aufruf verwendet.
Um dieses Problem zu vermeiden, können Sie diese Werte in Filterparametern mit JSON-Formatierung platzieren. Wenn Sie beispielsweise nach dem Benutzernamen-Testbenutzer filtern möchten, anstatt
/attask/api/v15.0/user/search?Benutzername=testuser@workfront.com
/attask/api/v15.0/user/search?filters={"username":"testuser@workfront.com"}
Verwenden des Map Request-Parameters
Standardmäßig sind die von einer Suche zurückgegebenen Daten ein JSON-Array. Je nach Anwendungsfall kann es effizienter sein, das Ergebnis als JSON-Objekt nach ID zu indizieren. Dies kann mithilfe des map -Anforderungsparameters erfolgen. Beispielsweise die Anfrage
/attask/api/v15.0/task/search?map=true
{
"data": {
"4c9a97db0000000f13ee4446b9aead9b": {
"percentComplete": 0,
"status": "NEW",
"name": "first task",
"ID": "4c9a97db0000000f13ee4446b9aead9b",
"taskNumber": 1
},
"4ca28ba600002024cd49e75bd43cf601": {
"percentComplete": 0,
"status": "INP:A",
"name": "second task",
"ID": "4ca28ba60002024cd49e75bd43cf601",
"taskNumber": 2
}
}
Verwenden des Feldanfrageparameters
Beim Abrufen eines Objekts werden standardmäßig nur die am häufigsten verwendeten Felder zurückgegeben.
Sie können den Feldanforderungsparameter verwenden, um eine kommagetrennte Liste bestimmter Felder anzugeben, die zurückgegeben werden. Beispielsweise die Anfrage
/attask/api/v15.0/task/search?fields=scheduledStartDate,priority
{
"priority": 2,
"name": "first task",
"ID": "4c7c08fa000002ff924e298ee148df4",
"scheduledStartDate": "2010-08-30T09:00:00:000-0600"
Eine Liste möglicher Feldverweise finden Sie unter API-Explorer
Suchen nach verschachtelten Objekten
Sie können nach verschachtelten Objekten suchen. Standardmäßig werden verschachtelte Objekte nur mit dem Namen und der ID zurückgegeben. Um beispielsweise alle Probleme zusammen mit den Eigentümern abzurufen, verwenden Sie die folgende Anfrage:
/attask/api/v15.0/issue/search?fields=owner
/attask/api/v15.0/issue/search?fields=owner:title,owner:phoneNumber
{
"name": "an important issue",
"ID": "4c78285f0000908ea8cfd66e084939f",
"owner": {
"title": "Operations Specialist",
"phoneNumber": "555-1234",
"name": "Admin User",
"ID": "4c76ed7a0000054c172b2c2d9f7f81c3"
}
Abrufen verschachtelter Sammlungen
Sie können verschachtelte Sammlungen von Objekten abrufen. Um beispielsweise ein Projekt mit allen seinen Aufgaben zu erhalten, verwenden Sie die folgende Anfrage:
/attask/api/v15.0/project/search?fields=tasks
/attask/api/v15.0/task/search?fields=assignments
Suchen nach mehreren verschachtelten Feldern
Standardmäßig werden nur der Name und die ID jeder Aufgabe zurückgegeben, es können jedoch zusätzliche verschachtelte Felder mit Doppelsyntax angegeben werden. Um alle verfügbaren Felder für ein verwandtes Objekt oder eine Sammlung anzuzeigen, hängen Sie einfach einen Doppelpunkt und ein Sternchen an die Objekt-/Sammlungsreferenz an.
/attask/api/v15.0/task/search?fields=assignments:*
Abrufen benutzerdefinierter Daten
Sie können benutzerdefinierte Datenfelder mit dem Präfix "DE:"abrufen. Um beispielsweise ein Projekt mit einem Parameter namens "CustomText"anzufordern, verwenden Sie die folgende Anfrage:
/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:CustomCheckBoxes": ["first", "second", "third"]
}
Verwenden von benannten Abfragen
Einige Objektarten haben spezifische Suchen, die häufig ausgeführt werden und verfügbar sind, indem der Name der Abfrage an das Ende des URI des Objekttyps angehängt wird. Beispielsweise ruft die folgende Anfrage die Arbeitselemente (Aufgaben und Probleme) ab, denen der Benutzer derzeit zugewiesen ist:
/attask/api/v15.0/work/myWork
Verwenden von Count
Mit count
können Sie die Anzahl der Ergebnisse zurückgeben, die Ihrer Abfrage entsprechen. Dies kann nützlich sein, wenn Sie die Daten in den Ergebnissen nicht benötigen. Wenn nur die Anzahl zurückgegeben wird, kann der Server die Anforderung schneller verarbeiten und Bandbreite sparen. Beispielsweise die Anfrage
GET /attask/api/v15.0/project/count?status=CUR
{
"count": 3
Anfordern eines Berichts
Sie können eine Berichtsanforderung durchführen, bei der nur das Aggregat eines Felds mit einer oder mehreren Gruppierungen gewünscht wird. Wie im folgenden Beispiel gezeigt, entspricht die Berichtssyntax der Syntax für die 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
}
Sortieren von Abfrageergebnissen in der API
Sie können Ihre Ergebnisse nach jedem Feld sortieren, wenn Sie Folgendes an Ihren API-Aufruf anhängen:
&entryDate_Sort=asc
Wenn Sie beispielsweise nach Aufgabe Geplantes Startdatum sortieren möchten, entfernen Sie entryDate und ersetzen Sie es durch scheduledCompletionDate.
Dies funktioniert für die meisten Felder in Workfront.
Abfragebeschränkungen berücksichtigen
Bei der Abfrage eines Objekts sollten die Beziehung verwandter Objekte und Suchbeschränkungen besonders berücksichtigt werden. Beispielsweise kann eine Abfrage nach Projekten, wie in der folgenden Tabelle dargestellt, maximal 2.000 Projekte zurückgeben. Diese 2.000 Projekte gelten als "primäre Objekte". Wenn Sie in den Projekten das Feld Aufgaben abfragen, wird das Feld Aufgaben (eine Sammlung) zum sekundären Objekt des primären Objektprojekts. Eine Abfrage für das Feld Aufgaben kann Tausende von Aufgaben für Projekte enthalten. Insgesamt kann die kombinierte Anzahl der zurückgegebenen Objekte (Projekte und Aufgaben) 50.000 nicht überschreiten.
Um eine optimale Leistung zu gewährleisten, werden in der folgenden Tabelle die Einschränkungen für Suchanfragen aufgeführt.
Anweisungen zum Außerkraftsetzen dieser Beschränkung finden Sie unter Verwenden von paginierten Antworten .
Verwenden von paginierten Antworten using-paginated-responses
Um die Begrenzung der Ergebnisanzahl (Default Number of Results) zu überschreiben und 200 Ergebnisse zuzulassen, können Sie den Filter $$LIMIT=200
in Ihre Abfrage einfügen, wie im folgenden Beispiel gezeigt:
GET /attask/api/v15.0/project/search?$$LIMIT=200
Um die Zuverlässigkeit und Leistung anderer Mandanten im System sicherzustellen, beträgt die maximal zulässige Ergebnisbegrenzung pro Abfrage 2000 Objekte. Wenn Sie versuchen, eine größere Begrenzung anzugeben, wird eine IllegalArgumentException
-Fehlermeldung angezeigt.
Daher empfehlen wir die Verwendung paginierter Antworten für große Datensätze. Um das erste Ergebnis anzugeben, das zurückgegeben werden soll, fügen Sie den Filter $$FIRST
hinzu. Beispielsweise gibt die folgende Anfrage die Ergebnisse 201-250 für eine Abfrage zurück:
GET /attask/api/v15.0/project/search?$$FIRST=200&$$LIMIT=50
Beachten Sie, dass im obigen Beispiel $$FIRST=200
das 201. Ergebnis zurückgibt. $$FIRST=0
gibt das erste Ergebnis zurück. Es kann hilfreich sein, sich den $$FIRST -Wert als die Anzahl der Ergebnisse vorzustellen, die Sie überspringen möchten, bevor Ergebnisse zurückgegeben werden.
Verwenden Sie einen Sortierparameter, um sicherzustellen, dass Ihre Ergebnisse korrekt paginiert werden. Dadurch können die Ergebnisse in derselben Reihenfolge zurückgegeben werden, sodass die Paginierung die Ergebnisse nicht wiederholt oder überspringt. Verwenden Sie beispielsweise ID_Sort=asc
, um die Sortierung mit der Objekt-ID vorzunehmen.
Erstellen einer Zugriffsregel
Sie können eine Zugriffsregel erstellen, um zu bestimmen, wer auf ein Objekt zugreifen kann. Im Folgenden finden Sie Beispiele für Zugriffsregeln, die Sie festlegen können:
Um ein Projekt so festzulegen, dass es nur für einen Benutzer mit der ID "abc123"freigegeben wird, verwenden Sie die folgende Anfrage:
GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxx?method=put &updates={ accessRules: [ {accessorID: 'abc123', accessorObjCode: 'USER', coreAction: 'VIEW'} ] }
GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxx/share?method=put&accessorID=abc123&accessorObjCode=USER&coreAction=VIEW
GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?fields=accessRules:*
Verhalten der POST
POST fügt ein neues Objekt ein. Die Syntax ist mit dem PUT identisch, allerdings mit einigen Ausnahmen. Da das neue Objekt noch nicht vorhanden ist, verfügt es über keine ID. Aus diesem Grund enthält der URI die ID nicht.
Erstellen eines Objekts
Im Folgenden finden Sie ein Beispiel für eine Anforderung zum Erstellen eines neuen Projekts:
POST /attask/api/v15.0/project?name=New Project
Kopieren eines Objekts
Einige Objekte unterstützen das Kopieren. Für diese Objekttypen ist es möglich, neue Objekte zu erstellen, indem Sie mit einem copySourceID -Parameter posten. Beispielsweise kopiert die folgende Anfrage das angegebene Projekt und gibt ihm einen neuen Namen:
POST /attask/api/v15.0/project?copySourceID=4c7...&name=Copied Project
Hochladen von Dokumenten
Sie können Dokumente über die folgende API-URL hochladen:
POST /attask/api/v15.0/upload
{
"handle": "4c7c08fa000002ff924e298ee148df4"
POST /attask/api/v15.0/document?updates={
name: aFileName,
handle: abc...123, (handle vom Datei-Upload)
docObjCode: PROJ, (oder TASK, OPTASK usw.)
objID: abc...123,
currentVersion:{version:v1.0,fileName:aFileName}
PUT-Verhalten
PUT wird verwendet, um ein vorhandenes Objekt zu aktualisieren.
Die Antwort für eine PUT ist identisch mit einer GET. In beiden Fällen gibt der Server den neuen Status des Objekts nach der Aktualisierung zurück. Alle Regeln, die zum Ändern einer Antwort auf eine GET-Anfrage verwendet werden, funktionieren auch mit PUT, z. B. die Angabe zusätzlicher zurückzugebender Felder, benutzerdefinierter Daten usw.
Bearbeiten von Objekten
Aktualisierungen von Objekten erfolgen immer per ID unter Verwendung des eindeutigen URI des Objekts. Zu aktualisierende Felder werden als Anforderungsparameter angegeben. Um beispielsweise den Namen eines Projekts zu ändern, können Sie eine Anfrage ähnlich der folgenden senden:
PUT /attask/api/v15.0/project/4c7..?name=New Project Name
PUT /attask/api/v15.0/project?id=4c7..&name=New Project Name
Angeben von JSON-Bearbeitungen
Wie im folgenden Beispiel gezeigt, können Sie den Parameter für Aktualisierungsanfragen verwenden, um die Felder anzugeben, die mit der JSON-Syntax aktualisiert werden sollen:
PUT /attask/api/v15.0/project/4c7..?updates=
{
name: "New Project Name",
status: "CUR",
...
Verschachtelte Aktualisierungen vornehmen
Einige Objekte verfügen über private Sammlungen, die aktualisiert werden können. Das folgende Beispiel zeigt beispielsweise, wie die vorhandenen Zuweisungen für eine bestimmte Aufgabe überschrieben werden:
PUT /attask/api/v15.0/task/4c7..?updates=
{
Zuweisungen: [
{
assignedToID: "222...54d0,
assignmentPercent: 50,0
},{
roleID: "111...54d0"
}
]
Im folgenden Beispiel wird ein Projekt zur Warteschlange eines öffentlichen Helpdesk. Beachten Sie, dass die vorhandenen Warteschlangeneigenschaften ersetzt werden.
PUT /attask/api/v15.0/project/4c7..?updates=
{
queueDef: {
isPublic: 1
}
Verwenden des Aktionsanfrageparameters
Einige Objekte unterstützen zusätzliche Aktionen, die zusätzlich zu einfachen Bearbeitungen durchgeführt werden können. Sie können diese Aktionen mithilfe des Aktionserforderungsparameters angeben. Beispielsweise wird mit der folgenden Anfrage die Timeline für ein bestimmtes Projekt neu berechnet:
PUT /attask/api/v15.0/project/4c7..?action=calculateTimeline
oder
PUT /attask/api/v15.0/project/4c7../calculateTimeline.
Verschieben von Objekten
Im Folgenden wird die Syntax zum Verschieben einer Aufgabe von einem Projekt in ein anderes veranschaulicht:
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/calculateFinance
PUT /attask/api/v15.0/project/1234/calculateTimeline{2 PUT /attask/api/v15.0/project/1234/calculateDataExtension
PUT /attask/api/v15.0/project/1234/recallApproval
PUT /attask/api/v15.0/project/1234/rejectApproval 5}PUT /attask/api/v15.0/task/1234/move
PUT /attask/api/v15.0/workitem/1234/markViewed
Im Folgenden finden Sie ein Beispiel für jeden Aktionstyp:
PUT /attask/api/v15.0/project/1234?method=put&updates={accessRules:[{accessorID: 'abc123', accessorObjCode: 'USER', coreAction: 'VIEW'}}
Freigeben von Objekten
Das folgende Beispiel zeigt die Syntax für die Freigabe eines Projekts für ein Team:
PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/share?accessorID=123abcxxxxxxxxxxxxxxxxxxxxxxxxxx&accessorObjCode=TEAMOB
PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?method=PUT&updates={accessRules:[{accessorID:'123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',accessorObjCode:'TEAMOB',Aktion:'VIEW'}}
PUT /attask/api/v15.0/task/4c7../move?projectID=5d8...
Verhalten von DELETEN
DELETE entfernt ein Objekt. In jedem Fall kann der URI den Parameter force=true enthalten, damit der Server die angegebenen Daten und die abhängigen Elemente entfernt. Im folgenden Beispiel wird eine Aufgabe gelöscht, indem die HTTP-DELETE-Methode für einen URI ausgeführt wird:
DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0
DELETE /attask/api/v15.0/task?id=4c7882 1c0000d6fa8d5e52f07a1d54d0
DELETE /attask/api/v15.0/task/4c7821c0000d6fa8d5e52f07a1d5 4d0?force=true
DELETE /attask/api/v15.0/task?id=4c78821c0000d6fa8d5e52f07a1d54d0?force=true
Massenaktualisierungen
Eine Massen-Update-Anweisung aktualisiert mehrere Objekte gleichzeitig in einem einzelnen API-Aufruf. Ein Bulk-create-API-Aufruf wird ähnlich wie ein normaler Update-Aufruf erstellt, wie in den folgenden Beispielen gezeigt:
PUT /attask/api/v15.0/proj?updates=[{"name":"Test_Project_1"},{"name":"Test_Project_2"}]&method=POST&apiKey=123ab-cxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
data: [
ID: "53ff8d3d003b438b57a8a784df38f6b3",
name: "Test_Project_1",
objCode: "PROJ",
percentComplete: 0,
scheduledCompleteDate: "2014-08-28T11:00:00:000-0400",
scheduledStartDate: "2014-08-28T11:00:00:000-0400",
priority: 0,
forecastCompletionDate: "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,
forecastCompletionDate: "2014-08-28T16:12:00:000-0400",
status: "CUR"
]
PUT /attask/api/v15.0/proj?Umethod=PUT&updates=[{"ID":"123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","name":"Test_Project_1_ Bearbeiten"},{"ID":"123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.","name":"Test_Project_2_Edit"}]&apiKey=123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
data: [ {
ID: "53ff8e15003b461d4560f7f65a440078",
name: "Test_Project_1_Edit",
objCode: "PROJ",
percentComplete: 0,
scheduledCompleteDate: "2014-08-28T11:00:00:000-0400",
scheduledStartDate: "2014-08-28T11:00:00:000-0400",
priority: 0,
forecastCompletionDate: "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,
forecastCompletionDate: "2014-08-28T16:16:00:000-0400",
status: "CUR"
]