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:

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 Schreibvorgänge an die Datenbank ausführt oder diese löscht, kann nur ausgeführt werden, wenn die Variable sessionID=abc123 ist im URI enthalten. 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=abc123

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. Das hat den Vorteil, dass man vor Cross-Site Request Forgery (CSRF) greift zu und stört nicht den URI zum Zwischenspeichern.

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

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:

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 übereinstimmt, dass /attask/api/v15.0/project/... -Anfrage.

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

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=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 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-060" 
}

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": "ein wichtiges Problem",
    "ID": "4c78285f0000908ea8cfd66e084939f",
    "owner": {
        "title": "Operations Specialist",
        "phoneNumber": "555-1234",
        "name": "Admin User",
        "ID": "4c76ed7a000054c172b2c2d9f7f81c3" 
    } 
}

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 Count

Sie können count 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. 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.

Verwenden von paginierten Antworten using-paginated-responses

Um die Begrenzung der Anzahl der Ergebnisse-Standardabfragen zu überschreiben und 200 Ergebnisse zuzulassen, können Sie die Variable $$LIMIT=200 in Ihrer Abfrage zu filtern, 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.

Daher empfehlen wir die Verwendung paginierter Antworten für große Datensätze. Um das erste zurückgegebene Ergebnis anzugeben, fügen Sie die $$FIRST Filter. 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 gibt das 201. Ergebnis zurück. $$FIRST=0 das erste Ergebnis zurückgeben. 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 zum Beispiel zur Sortierung mit der Objekt-ID 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 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: "2222...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

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

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

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

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=4c78821c0000d6fa8d5e52f07a1d54d0 
DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0?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"
    Priorität: 0,
    forecastCompletionDate: "2014-08-28T16:12:00:000-0400"
    status: "CUR"
},
{
    ID: "53ff8d49003b43a2562aa34eea3b6b10",
    name: "Test_Project_2",
    objCode: "PROJ",
    percentComplete: 0usi,
    scheduledCompleteDate: "2014-08-28T11:00:00:000-0400"
    scheduledStartDate: "2014-08-28T11:00:00:000-0400"
    Priorität: 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"
     Priorität: 0,
     forecastCompletionDate: "2014-08-28T16:16:00:000-0400"
     status: "CUR"
},
{
    ID: "53ff8e19003b46238a58d303608de502",
    name: "Test_Project_2_Edit",
    objCode: "PROJ",
    percentComplete: 0,
    scheduledCompleteDate: "2014-08-28T11:00:00:000-0400"
    scheduledStartDate: "2014-08-28T11:00:00:000-0400"
    Priorität: 0,
    forecastCompletionDate: "2014-08-28T16:16:00:000-0400"
    status: "CUR"
}]