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 werden kann. In diesem Dokument wird davon ausgegangen, dass Sie mit REST- und JSON-Antworten vertraut sind, und der von der Workfront-API verfolgte Ansatz beschrieben.
Wenn Sie mit dem Workfront-Schema vertraut sind, können Sie die Datenbankbeziehungen verstehen, die Sie verwenden können, um Daten aus Workfront für Integrationszwecke abzurufen.
Beschrä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. Die Sandbox-Umgebung verfügt über dieselbe maximale Anzahl gleichzeitiger API-Threads, sodass Kundinnen und Kunden sowie Partner API-Aufrufe genau testen können, bevor Code für die Produktion freigegeben wird.
Für Produktions-, Vorschau- und Testlaufwerk-Umgebungen haben Endbenutzeranfragen 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 Beta-Umgebung von Workfront getestet werden, bevor sie in der Produktionsumgebung ausgeführt wird. Wenn ein Kunde die -API für einen Prozess verwendet, von dem Workfront vernünftigerweise annimmt, dass er die On-Demand-Software belastet (d. h. der Prozess hat für andere Kunden wesentliche negative Auswirkungen auf die Leistung der Software), behält sich Workfront das Recht vor, den Kunden aufzufordern, diesen Prozess einzustellen. Wenn der Kunde die Vorgaben nicht erfüllt und das Problem weiterhin besteht, behält sich Workfront das Recht vor, den Vorgang zu beenden.
Workfront-API-URL
Informationen über die URL, die Sie zum Aufrufen der Workfront-API verwenden werden, finden Sie unter Domain-Format für Adobe Workfront-API-Aufrufe.
REST-Grundlagen
In diesem Abschnitt finden Sie eine allgemeine Einführung in die Interaktion mit der Workfront REST-API für die folgenden REST-Prinzipien:
Objekt-URI
Jedem Objekt im System wird ein eindeutiger URI zugewiesen, 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
Bei dem Objekttyp wird nicht zwischen Groß- und Kleinschreibung unterschieden und es kann sich entweder um den abgekürzten ObjCode (z. B. proj) oder den alternativen Objektnamen (project) handeln.
Eine Liste der Objekte, gültigen ObjCodes und Objektfelder finden Sie unter API-Explorer.
Category
und ein benutzerdefiniertes Feld ein Parameter
.Vorgänge
Objekte werden durch Senden einer HTTP-Anfrage an den eindeutigen URI bearbeitet. 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 nach allen Objekten anhand einer Abfrage, führt Berichte aus oder führt benannte Abfragen aus
- POST - Fügt ein neues Objekt ein
- PUT - Bearbeitet ein vorhandenes Objekt
- DELETE - Löscht ein Objekt
Um Client-Mängel oder Protokolllängenbeschränkungen zu umgehen, kann der Methodenparameter verwendet werden, um das HTTP-Verhalten zu überschreiben. Beispielsweise kann ein GET-Vorgang implementiert werden, indem der folgende URI gepostet wird:
GET /attask/api/v15.0/project?id=4c78…54d0&method=get
GET /attask/api/v15.0/project/4c78…54d0?method=get
Antwort
Jede Anfrage erhält eine Antwort im JSON-Format. Die Antwort enthält entweder ein Datenattribut, wenn die Anfrage erfolgreich war, oder ein Fehlerattribut, wenn ein Problem aufgetreten ist. Beispiel: die Anfrage
GET /attask/api/v15.0/proj/4c7c08b20000002de5ca1ebc19edf2d5
gibt eine JSON-Antwort ähnlich der folgenden zurück:
{
„data“: [
{
„percentComplete“: 0,
„status“: „CUR“,
„Priorität“: 2,
„name“: „Brand New Project“,
„ID“: „4c7c08b20000002de5ca1ebc19edf2d5“
}
]
}
Besondere Sicherheit wurde für PUT-, POST- und DELETE-Anfragen hinzugefügt. Jede Anfrage, die zum Schreiben in oder Löschen aus der Datenbank führt, kann nur ausgeführt werden, wenn sessionID=abc123 im URI enthalten ist. Die folgenden Beispiele zeigen, wie dies bei einer DELETE-Anfrage aussehen 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=abc123
Authentifizierung
Die API authentifiziert jede Anfrage, um sicherzustellen, dass der Client Zugriff zum Anzeigen oder Ändern eines angeforderten Objekts hat.
Die Authentifizierung erfolgt durch Übergabe einer Sitzungs-ID, die mithilfe einer der folgenden Methoden erteilt werden kann:
Authentifizierung beim Anforderungsheader
Die bevorzugte Authentifizierungsmethode besteht darin, einen Anfrage-Header mit dem Namen SessionID zu übergeben, der das Sitzungs-Token enthält. Dies hat den Vorteil, dass es vor Cross-Site Request Forgery (CSRF)-Angriffenist und den URI zu Caching-Zwecken nicht beeinträchtigt.
Im Folgenden finden Sie ein Beispiel für einen Anfrage-Header:
GET /attask/api/v15.0/project/search
SessionID: abc1234
Cookie-basierte Authentifizierung
Die API verwendet dieselbe Cookie-basierte Authentifizierung wie die Web-Benutzeroberfläche im System. Wenn sich ein Client über die Web-Benutzeroberfläche bei Workfront anmeldet, verwenden alle AJAX-Aufrufe innerhalb desselben Browsers dieselbe Authentifizierung.
Anmeldung
/login
-Endpunkts oder der API-Schlüssel. Verwenden Sie stattdessen eine der folgenden Authentifizierungsmethoden:- Server-Authentifizierung mit JWT
- Benutzerauthentifizierung mit OAuth2
Mit einem gültigen Benutzernamen und Kennwort können Sie die folgende Anfrage verwenden, um eine Sitzungs-ID abzurufen:
POST /attask/api/v15.0/login?username=admin&password=user
Damit wird ein Cookie gesetzt, um zukünftige Anfragen zu authentifizieren und eine JSON-Antwort mit der neu erstellten Sitzungs-ID, 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
Sie können dieses Ergebnis dann verwenden, um jeden API-Aufruf zu authentifizieren, indem Sie „apiKey“ als Abfrageparameter mit diesem Wert anstelle einer Sitzungs-ID oder eines Benutzernamens und Kennworts hinzufügen. Dies ist aus Sicherheitssicht von Vorteil.
Die folgende Anfrage ist ein Beispiel für das Abrufen von Daten aus einem Projekt mithilfe des -API-Schlüssels:
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, wodurch der aktuelle API-Schlüssel ungültig wird, wie im folgenden Beispiel gezeigt:
GET /attask/api/v15.0/user?action=clearApiKey&username=user@email.com&password=userspassword&method=put
Nach dem Löschen 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 und so jeden weiteren Zugriff mit der Sitzungs-ID zu verhindern.
GET /attask/api/v15.0/logout?sessionID=abc1234
Die Sitzungs-ID, die abgemeldet werden soll, 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 wurde. -
Ersetzen Sie das Wort Suche durch Anmelden?username=admin&password=user und ersetzen Sie admin und *user durch Ihren Benutzernamen und Ihr Kennwort
*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 in /attask/api/v15.0/project/search.
-
Beachten Sie die bereitgestellte Antwort.
Bei PUT-, POST- und DELETE-Anfragen muss nach der Anmeldung immer die Sitzungs-ID angegeben werden.
Verhalten von GET
Verwenden Sie die HTTP-GET-Methode zum Abrufen eines oder mehrerer Objekte und zum Ausführen von Berichten.
Objekte werden abgerufen
Sie können die Suche nach Objekten mithilfe von Modifikatoren und Filtern verbessern.
Abrufen eines -Objekts mithilfe der Objekt-ID
Wenn Sie die ID eines -Objekts kennen, können Sie das -Objekt durch Zugriff auf seinen eindeutigen URI abrufen. Beispiel: die Anfrage
GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
Gibt eine Antwort ähnlich der folgenden zurück:
{
„percentComplete“: 0,
„status“: „CUR“,
„Priorität“: 2,
„name“: „Brand New Project“,
„ID“: „4c7c08b20000002de5ca1ebc19edf2d5“
}
Sie können mehrere Objekte in derselben Anfrage abrufen, indem Sie den Anforderungsparameter id 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 Anfrage /attask/api/v15.0/project?id=… mit der /attask/api/v15.0/project/...
-Anfrage übereinstimmt.
Abrufen eines -Objekts mithilfe des URI
Wenn Sie ein Objekt nach anderen 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 Anfrageparameter als Name-Wert-Paare angeben. Das folgende Beispiel zeigt beispielsweise eine Anfrage, die alle aktuellen Projekte finden würde:
GET /attask/api/v15.0/project/search?status=CUR
Die folgende Anfrage findet alle Aufgaben, die noch nicht abgeschlossen sind und die einem Benutzer namens „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_mode=ne…
…percentComplete=50&percentComplete_Mod=get…
…percentComplete=50&percentComplete_Mod=lte…
…description_mod=isNull…
…description_mod=notNull…
…name=Workfront&name_mod=enthält…
…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…
Verwenden von OR-Anweisungen
Sie können eine Suche verbessern, indem Sie einen Parameter hinzufügen, der „OR“ sowie eine Zahl enthält, um die Ebene eines Filters oder einer Reihe von Filtern anzugeben.
Eine OR-Anweisung gibt nur Datensätze im API-Aufruf zurück, die den Filterkriterien der OR-Anweisung entsprechen. Filter sind nicht auf allen OR-Anweisungsebenen impliziert.
Wenn Sie beispielsweise nach filtern möchten
- Aufgaben mit einem Namen, der „Planung“ ODER enthält
- Aufgaben in einem Portfolio mit dem Namen „FixedAssets“ UND jemandem mit einem Namen zugewiesen, der „Steve“ ODER enthält
- Aufgaben mit einer übergeordneten Aufgabe namens „Endgültige Aufgabe“
verwenden Sie dann den folgenden API-Aufruf mit seinen mehreren OR-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=cicontains
&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 (z. B. Benutzername, Kennwort, API-Schlüssel, Cookie) gesucht wird. 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 „testuser“ filtern möchten, anstatt zu verwenden
/attask/api/v15.0/user/search?username=testuser@workfront.com
/attask/api/v15.0/user/search?filters={„username“:“testuser@workfront.com"}
Verwenden des Map-Anforderungsparameters
Standardmäßig sind die von einer Suche zurückgegebenen Daten ein JSON-Array. Je nach Anwendungsfall ist es möglicherweise effizienter, das Ergebnis als ein nach ID indiziertes JSON-Objekt abzurufen. Verwenden Sie dazu den Anforderungsparameter „map“. Beispiel: 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“: „Zweite Aufgabe“,
„ID“: „4ca28ba600002024cd49e75bd43cf601“,
„taskNumber“: 2
}
}
}
Verwenden des Anforderungsparameters Fields
Standardmäßig wird beim Abrufen eines -Objekts nur die am häufigsten verwendete Teilmenge von Feldern zurückgegeben.
Mit dem Anforderungsparameter fields können Sie angeben, dass eine kommagetrennte Liste bestimmter Felder zurückgegeben wird. Beispiel: die Anfrage
/attask/api/v15.0/task/search?fields=scheduledStartDate,priority
{
„Priorität“: 2,
„name“: „first task“,
„ID“: „4c7c08fa0000002ff924e298ee148df4“,
„scheduledStartDate“: „2010-08-30T09:00:00:000-0600“
}
Eine Liste der möglichen Feldverweise finden Sie in der 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. Verwenden Sie beispielsweise die folgende Anfrage, um alle Probleme mit ihren Besitzern zu klären:
/attask/api/v15.0/issue/search?fields=owner
/attask/api/v15.0/issue/search?fields=owner:title,owner:phoneNumber
{
„Name“: „Ein wichtiges Thema“,
„ID“: „4c78285f00000908ea8cfd66e084939f“,
„Inhaber“: {
„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 abzurufen, 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 Doppelpunkt-Syntax angegeben werden. Um alle verfügbaren Felder für ein verknüpftes Objekt oder eine Auflistung anzuzeigen, hängen Sie einfach einen Doppelpunkt und ein Sternchen an die Objekt-/Sammlungsreferenz an.
/attask/api/v15.0/task/search?fields=assignments:*
Benutzerdefinierte Daten werden abgerufen
Benutzerdefinierte Datenfelder können mit dem Präfix „DE:“ abgerufen werden. 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“: „Benutzerdefiniertes Datenprojekt“,
„ID“: „4c9a954f0000001afad0687d7b1b4e43“,
„DE:CustomText“: „task b“
}
/attask/api/v15.0/project/search?fields=parameterValues
{
„Name“: „Benutzerdefiniertes Datenprojekt“,
„ID“: „4c9a954f0000001afad0687d7b1b4e43“,
parameterValues: {
„DE:CustomText“: „task b“,
„DE:CustomNumber“: 1.4,
„DE:CustomCheckBoxes“: [„first“, „second“, „third“]
}
}
Verwenden benannter Abfragen
Einige Objekttypen verfügen über benannte Suchvorgänge, die häufig ausgeführt werden und verfügbar sind, indem der Name der Abfrage an das Ende des Objekttyp-URI 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
Sie können count
verwenden, um die Anzahl der Ergebnisse zurückzugeben, die Ihrer Abfrage entsprechen. Dies kann nützlich sein, wenn Sie die Daten in den Ergebnissen nicht benötigen. Durch die Rückgabe der Zählung kann der Server die Anfrage schneller verarbeiten und Bandbreite sparen. Beispiel: die Anfrage
GET /attask/api/v15.0/project/count?status=CUR
{
„count“: 3
}
Bericht anfordern
Sie können eine Berichtsanfrage ausführen, bei der mit einer oder mehreren Gruppierungen nur die Zusammenfassung eines Felds gewünscht wird. Wie im folgenden Beispiel gezeigt, ist die Berichtssyntax mit der Syntax für die SOAP-API identisch:
GET /attask/api/v15.0/hour/report?project:name_1_GroupBy=true&hours_AggFunc=sum
{
„Erstes Projekt“: {
„sum_hours“: 15
},
„Zweites Projekt“: {
„sum_hours“: 30
}
}
{
„Erstes Projekt“: {
„sum_hours“: 15
},
„Zweites Projekt“: {
„sum_hours“: 30
},
"$$ROLLUP“: {
„sum_hours“: 45
}
}
Sortieren von Abfrageergebnissen in der API
Sie können Ihre Ergebnisse nach einem beliebigen Feld sortieren, wenn Sie Folgendes an Ihren API-Aufruf anhängen:
&entryDate_Sort=asc
Wenn Sie beispielsweise nach dem geplanten Startdatum der Aufgabe sortieren möchten, entfernen Sie entryDate und ersetzen Sie es durch scheduledCompletionDate.
Dies funktioniert für die meisten Felder in Workfront.
Überlegungen zu Abfragebeschränkungen
Bei der Abfrage eines Objekts sollte die Beziehung verwandter Objekte und Sucheinschränkungen besonders berücksichtigt werden. Wie in der folgenden Tabelle dargestellt, kann eine Abfrage für Projekte beispielsweise nicht mehr als 2.000 Projekte zurückgeben. Diese 2.000 Projekte werden als „primäre Objekte“ betrachtet. Wenn Sie für die Projekte das Feld Aufgaben abfragen, wird das Feld Aufgaben , das eine Sammlung ist, zum sekundären Objekt des primären Projektobjekts. Eine Abfrage für das Feld Aufgaben kann Tausende von Aufgaben in Projekten enthalten. Insgesamt darf die Gesamtanzahl 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 bei Suchanfragen aufgeführt.
Anweisungen zum Überschreiben dieser Beschränkung finden unter „Verwendenpaginierten Antworten“.
Verwenden paginierter Antworten using-paginated-responses
Um die Standardabfragebeschränkung für die Anzahl der Ergebnisse zu überschreiben und 200 Ergebnisse zuzulassen, können Sie den $$LIMIT=200
-Filter in Ihre Abfrage einbeziehen, 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 Ergebnisgrenze pro Abfrage 2.000 Objekte. Der Versuch, eine größere Grenze anzugeben, führt zu einer IllegalArgumentException
Fehlermeldung.
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 $$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
würde das erste Ergebnis zurückgeben. Es kann hilfreich sein, sich den Wert $$FIRST als die Anzahl der Ergebnisse vorzustellen, die Sie überspringen möchten, bevor Sie Ergebnisse zurückgeben.
Um sicherzustellen, dass Ihre Ergebnisse ordnungsgemäß paginiert werden, verwenden Sie einen Sortierparameter. Dadurch können die Ergebnisse in derselben Reihenfolge zurückgegeben werden, sodass die Paginierung die Ergebnisse nicht wiederholt oder überspringt. Um beispielsweise anhand der Objekt-ID zu sortieren, verwenden Sie ID_Sort=asc
.
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 einzurichten, 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/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/share?method=put&accessorID=abc123&accessorObjCode=USER&coreAction=VIEW
GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?fields=accessRules:*
Verhalten der POST
POST fügt ein neues -Objekt ein. Die Syntax entspricht der von PUT, 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 Anfrage zum Erstellen eines neuen Projekts:
POST /attask/api/v15.0/project?name=Neues Projekt
Kopieren eines Objekts
Einige Objekte unterstützen das Kopieren. Für diese Objekttypen ist es möglich, neue Objekte durch Posten mit einem copySourceID-Parameter zu erstellen. 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
{
„Griff“: „4C7C08FA0000002FF924E298EE148DF4“
}
POST /attask/api/v15.0/document?updates={
name: aFileName,
handle: abc…123, (handle from the file 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 beim PUT, z. B. die Angabe zusätzlicher zurückzugebender Felder, benutzerdefinierter Daten usw.
Objekte bearbeiten
Aktualisierungen an Objekten werden immer nach ID unter Verwendung der eindeutigen URI des Objekts durchgeführt. Zu aktualisierende Felder werden als Anfrageparameter 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 Anforderungsparameter „updates“ verwenden, um die zu aktualisierenden Felder mithilfe der JSON-Syntax anzugeben:
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. Im folgenden Beispiel wird beispielsweise veranschaulicht, wie die vorhandenen Zuweisungen für eine bestimmte Aufgabe überschrieben werden:
PUT /attask/api/v15.0/task/4c7…?Updates=
{
Arbeitsaufträge: [
{
assignedToID: „2222…54d0,
assignmentPercent: 50,0
},{
roleID: „1111…54d0“
}
]
}
Im folgenden Beispiel wird ein Projekt zu einer öffentlichen Helpdesk-Warteschlange. Beachten Sie, dass die vorhandenen Warteschlangeneigenschaften ersetzt werden.
PUT /attask/api/v15.0/project/4c7…?Updates=
{
queueDef: {
isPublic: 1
}
}
Verwenden des Aktionserforderungsparameters
Einige Objekte unterstützen zusätzlich zu einfachen Bearbeitungen weitere Aktionen, die ausgeführt werden können. Sie können diese Aktionen mit dem Aktionserforderungsparameter angeben. Mit der folgenden Anfrage wird beispielsweise die Zeitleiste für ein bestimmtes Projekt neu berechnet:
PUT /attask/api/v15.0/project/4c7…?action=calculateTimeline
or
PUT /attask/api/v15.0/project/4c7…/calculateTimeline
Objekte werden verschoben
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/approve
PUT /attask/api/v15.0/project/1234/calculateFinance
PUT /attask/api/v15.0/project/1234/calculateTimeline
PUT /attask/api/v15.0/project/1234/calculateDataExtension
PUT /attask/api/v15.0/project/1234/recallApproval
PUT /attask/api/v15.0/project/1234/approve
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/123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxx/share?accessorID=123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxx&accessorObjCode=TEAMOB
PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?method=PUT&updates={accessRules:[{accessorID:'123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',accessorObjCode:'TEAMOB',coreAction:'VIEW'}]}
PUT /attask/api/v15.0/task/4c7…/move?projectID=5d8…
Verhalten des DELETE
DELETE entfernt ein Objekt. In jedem Fall kann der URI den Parameter force=true enthalten, damit der Server die angegebenen Daten und deren 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=4c78821c0000d6fa8d5e52f07a1d54d0
DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0?force=true
DELETE /attask/api/v15.0/task?id=4c78821c0000d6fa8d5e52f07a1d54d0?force=true
Massenaktualisierungen
Eine Massen-Aktualisierungsanweisung aktualisiert innerhalb eines einzigen API-Aufrufs mehrere Objekte gleichzeitig. Ein Massenerstellungs-API-Aufruf wird ähnlich wie ein normaler Aktualisierungsaufruf 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
Daten: [{
ID: „53ff8d3d003b438b57a8a784df38f6b3“,
Name: „test_project_1“,
objCode: „PROJ“,
percentComplete: 0,
scheduledCompletionDate: „2014-08-28T11:00:00:000-0400“,
geplantes Startdatum: „2014-08-28T11:00:00:000-0400“,
Priorität: 0,
projectionCompletionDate: „2014-08-28T16:12:00:000-0400“,
Status: „CUR“
},
{
Kennung: „53ff8d49003b43a2562aa34ea3b6b10“,
Name: „test_project_2“,
objCode: „PROJ“,
percentComplete: 0usi,
scheduledCompletionDate: „2014-08-28T11:00:00:000-0400“,
geplantes Startdatum: „2014-08-28T11:00:00:000-0400“,
Priorität: 0,
projectionCompletionDate: „2014-08-28T16:12:00:000-0400“,
Status: „CUR“
}]
PUT /attask/api/v15.0/proj?umethod=PUT&updates=[{„ID“:„123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx“,„name“:„Test_Project_1_ Edit“},{„ID“:„123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}]&apiKey=123abcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Daten: [ {
Kennung: „53ff8e15003b461d4560f7f65a440078“,
Name: „test_project_1_edit“,
objCode: „PROJ“,
percentComplete: 0,
scheduledCompletionDate: „2014-08-28T11:00:00:000-0400“,
geplantes Startdatum: „2014-08-28T11:00:00:000-0400“,
Priorität: 0,
projectionCompletionDate: „2014-08-28T16:16:00:000-0400“,
Status: „CUR“
},
{
Kennung: „53ff8e19003b46238a58d303608de502“,
Name: „test_project_2_edit“,
objCode: „PROJ“,
percentComplete: 0,
scheduledCompletionDate: „2014-08-28T11:00:00:000-0400“,
geplantes Startdatum: „2014-08-28T11:00:00:000-0400“,
Priorität: 0,
projectionCompletionDate: „2014-08-28T16:16:00:000-0400“,
Status: „CUR“
}]