DokumentationWorkfrontHandbuch für Workfront

API-Grundlagen

Last update: Fri Apr 24 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Themen:

Erstellt für:

  • Entwickler

Das Ziel der Adobe Workfront-API ist die Vereinfachung der Erstellung von Integrationen mit Workfront, indem eine REST-ful-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 der von der Workfront-API verfolgte Ansatz wird beschrieben.

Wenn Sie mit dem Workfront-Schema vertraut sind, ist es einfacher, die Datenbankbeziehungen zu 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 8.892 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 bzw. eine Kundin die API für einen Prozess verwendet, von dem Workfront nach vernünftiger Einschätzung annimmt, dass er die On-Demand-Software belastet (d. h. der Prozess hat erhebliche negative Auswirkungen auf die Leistung der Software für andere Kundschaft), behält sich Workfront das Recht vor, die Person aufzufordern, diesen Prozess einzustellen. Wenn der Kunde bzw. die Kundin der Aufforderung nicht nachkommt 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-Grundsätze:

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

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

NOTE
Im Kontext der Workfront-API ist ein benutzerdefiniertes Formular ein Category-Objekt und ein benutzerdefiniertes Feld ein Parameter-Objekt.

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 Protokoll-Lä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. Beispielsweise gibt die Anfrage

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

gibt eine JSON-Antwort ähnlich der folgenden zurück:

{
    "data": [
        {
            "percentComplete": 0,
            "status": "CUR",
            "priority": 2,
            "name": "Brand New Project",
            "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
        } 
    ] 
}
NOTE
Beim Ausführen einer GET-Anfrage über die Adressleiste Ihres Browsers ist es nicht erforderlich, die Sitzungs-ID als Teil der Anfrage einzuschließen.

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 vergeben werden kann:

Anfrage-Header-Authentifizierung

Die bevorzugte Authentifizierungsmethode besteht darin, einen Anfrage-Header mit dem Namen SessionID zu übergeben, der das Sitzungs-Token enthält. Diese hat den Vorteil, dass sie sicher vor Cross-Site Request Forgery (CSRF)-Angriffen ist 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

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, nutzen alle AJAX-Aufrufe innerhalb desselben Browsers dieselbe Authentifizierung.

NOTE
Zum Schutz vor möglichen CSRF-Angriffen (Cross Site Request Forgery) ist diese Authentifizierungsmethode nur für schreibgeschützte Vorgänge verfügbar.

Anmeldung

IMPORTANT
Workfront empfiehlt die Verwendung des /login-Endpunkts oder der API-Schlüssel nicht mehr. Verwenden Sie stattdessen eine der folgenden Authentifizierungsmethoden:
  • Server-Authentifizierung mit JWT
  • Benutzerauthentifizierung mit OAuth2
Anweisungen zum Einrichten dieser Authentifizierungsmethoden finden Sie unter Erstellen von OAuth2-Anwendungen für Workfront-Integrationen
Anweisungen zur Verwendung der Server-Authentifizierung in Workfront finden Sie unter Konfigurieren und Verwenden der benutzerdefinierten OAuth 2-Anwendungen Ihres Unternehmens mithilfe des JWT-Flusses
Anweisungen zur Verwendung der Benutzerauthentifizierung in Workfront finden Sie unter Konfigurieren und Verwenden der benutzerdefinierten OAuth 2-Anwendungen Ihrer Organisation mithilfe des Autorisierungs-Code-Flusses
NOTE
Das in diesem Abschnitt beschriebene Verfahren galt nur für Organisationen, die noch nicht in die Adobe Business Platform integriert wurden. Da nun alle Organisationen in die Adobe Business-Plattform integriert wurden, ist die Anmeldung bei Workfront über die Workfront-API nicht mehr verfügbar .
Eine Liste der Verfahren, die sich je nachdem, ob Ihr Unternehmen die Adobe Business Platform verwendet, unterscheiden, finden Sie unter Administrationsunterschiede zwischen Adobe Workfront und Adobe Business Platform.

Mit einem gültigen Benutzernamen und einem 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 bzw. der angemeldeten Benutzerin und anderen Sitzungsattributen zurückzugeben.

NOTE
Wenn Sie über einen benannten API-Benutzer bzw. eine benannte API-Benutzerin verfügen, der bzw. die auch Admin ist, empfiehlt Workfront dringend, einen API-Schlüssel für die Anmeldung zu verwenden.

Generieren eines API-Schlüssels

Sie können einen API-Schlüssel generieren, wenn Sie sich als dieser Benutzer bzw. diese Benutzerin 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 bzw. eine bestimmte Benutzerin generiert wurde, indem Sie getApiKey ausführen:

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

Dieses Ergebnis können Sie dann verwenden, um jeden API-Aufruf zu authentifizieren, indem Sie „apiKey“ als Anfrageparameter mit diesem Wert anstelle einer Sitzungs-ID oder eines Benutzernamens und eines Kennworts hinzufügen. Dies ist aus einer Sicherheitsperspektive 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. Dadurch wird der aktuelle API-Schlüssel ungültig, 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 bzw. die Benutzerin 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, Anfrage-Header oder Anfrageparameter angegeben werden.

So melden Sie einen Benutzer bzw. eine Benutzerin ab:

  1. Navigieren Sie zu Ihrem Anmeldebildschirm, melden Sie sich jedoch nicht an.

  2. Ändern Sie die URL in „/attask/api/v15.0/project/search“.
    Beachten Sie, dass die Seite nicht gefunden wurde.

  3. Ersetzen Sie das Wort search durch „login?username=admin&password=user“ und ersetzen Sie Ihren Benutzernamen und Ihr Kennwort durch admin und „*user“
    *Diese Sitzung wird im Browser als Cookie gespeichert und muss nicht bei jeder nachfolgenden GET-Anfrage neu angegeben werden.

  4. Ändern Sie die URL zurück in /attask/api/v15.0/project/search.

  5. Beachten Sie die angegebene Antwort.

Bei PUT-, POST- und DELETE-Anfragen muss nach der Anmeldung immer die Sitzungs-ID angegeben werden.

GET-Verhalten

Verwenden Sie die HTTP-GET-Methode zum Abrufen eines oder mehrerer Objekte und zum Ausführen von Berichten.

Abrufen von Objekten

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. Beispielsweise gibt die Anfrage

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

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 Anfrage abrufen, indem Sie den Anfrageparameter „id“ 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/prBeaoject?id=…“ mit der Anfrage /attask/api/v15.0/project/... identisch ist.

Abrufen eines Objekts mithilfe des 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 Anfrageparameter als Name-Wert-Paare angeben. Das folgende Beispiel zeigt eine Anfrage, die alle aktuellen Projekte findet:

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.

Modifikator
Beschreibung
Beispiel
eq
Gibt Ergebnisse mit dem Status „Geschlossen“ zurück
…status=cls&status_Mod=eq…
ne
Gibt Ergebnisse zurück, die nicht den Status „Geschlossen“ haben
…status=cls&status_Mod=ne…
gte
Gibt Ergebnisse zurück, deren Prozentwert der Fertigstellung größer oder gleich 50 ist
…percentComplete=50&percentComplete_Mod=gte…
lte
Gibt Ergebnisse zurück, deren Prozentwert der Fertigstellung kleiner oder gleich 50 ist
…percentComplete=50&percentComplete_Mod=lte…
isnull
Gibt Ergebnisse zurück, bei denen die Beschreibung null ist
…description_Mod=isnull…
notnull
Gibt Ergebnisse zurück, bei denen die Beschreibung nicht null ist
…description_Mod=notnull…
contains
Gibt Ergebnisse zurück, bei denen der Name „Workfront“ enthält
…name=Workfront&name_Mod=contains…
between
Gibt Ergebnisse mit einem Eingabedatum innerhalb der letzten 7 Tage zurück
…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…
NOTE
Bei Suchanfragen wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie eine Fehlermeldung erhalten, stellen Sie sicher, dass  _Mod und _Range die korrekte Groß-/Kleinschreibung aufweisen.

Verwenden von ODER-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 ODER-Anweisung gibt nur Einträge im API-Aufruf zurück, die den Filterkriterien der ODER-Anweisung entsprechen. Filter werden nicht bei allen ODER-Anweisungsebenen impliziert.

Wenn Sie beispielsweise nach Folgendem filtern möchten

  • Aufgaben mit einem Namen, der „Planning“ enthält ODER
  • Aufgaben in einem Portfolio mit dem Namen „FixedAssets“ UND jemandem mit einem Namen zugewiesen, der „Steve“ enthält ODER
  • Aufgaben mit einer übergeordneten Aufgabe namens „Final Task“,

dann verwenden Sie den folgenden API-Aufruf mit seinen 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

Verwenden von Filterparametern

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 einfügen. Wenn Sie beispielsweise nach dem Benutzernamen „testuser“ filtern möchten, gehen Sie wie folgt vor: Anstatt

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

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

Verwenden des Anfrageparameters „map“

Standardmäßig handelt es sich bei den von einer Suche zurückgegebenen Daten um 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 Anfrageparameter „map“. Beispielsweise gibt 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": "4ca28ba600002024cd49e75bd43cf601",
            "taskNumber": 2 
        } 
    } 
}

Verwenden des Anfrageparameters „fields“

Standardmäßig wird beim Abrufen eines Objekts nur die am häufigsten verwendete Teilmenge von Feldern zurückgegeben.

Mit dem Anfrageparameter „fields“ können Sie angeben, dass eine kommagetrennte Liste bestimmter Felder zurückgegeben wird. Beispielsweise gibt die Anfrage

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

{
    "priority": 2,
    "name": "first task",
    "ID": "4c7c08fa0000002ff924e298ee148df4",
    "plannedStartDate": "2010-08-30T09:00:00:000-0600" 
}
NOTE
Bei diesen Feldnamen wird zwischen Groß- und Kleinschreibung unterschieden.

Eine Liste der möglichen 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. Verwenden Sie beispielsweise die folgende Anfrage, um alle Probleme zusammen mit ihren Inhabenden abzurufen:

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

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

{
    "name": "an important issue",
    "ID": "4c78285f00000908ea8cfd66e084939f",
    "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 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 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

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": "custom data project",
    "ID": "4c9a954f0000001afad0687d7b1b4e43",
    "DE:CustomText": "task b" 
}

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

{
    "name": "custom data project",
    "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 bzw. die Benutzerin 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. Wird nur die Anzahl zurückgegeben, kann der Server die Anfrage schneller verarbeiten und Bandbreite sparen. Beispielsweise gibt die Anfrage

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

{
    "count": 3 
}

Anfordern eines Berichts

Sie können eine Berichtsanfrage ausführen, bei der nur das Aggregat eines bestimmten Feldes mit einer oder mehreren Gruppierungen 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

{
    "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 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 sollten Überlegungen hinsichtlich der Beziehung zwischen Objekten und Suchbeschränkungen angestellt 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 das Feld „Aufgaben“ für die Projekte abfragen, wird das Feld „Aufgaben“, das eine Sammlung ist, zum sekundären Objekt des primären Objekts „Projekt“. 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.

Abfrageergebnis
Einschränkung
Beschreibung
Standardanzahl der Ergebnisse
100
Wenn im Abfragefilter (d. h. $$LIMIT) kein Limit angegeben ist, kann das Ergebnis nicht mehr als 100 primäre Objekte enthalten.
Unter Verwenden paginierter Antworten finden Sie Anweisungen zum Überschreiben dieser Einschränkung.
Max. Anzahl der Ergebnisse
2.000
Der Abfragefilter (d. h. $$LIMIT) kann nicht mehr als 2.000 Ergebnisse zurückgeben. Weitere Informationen finden Sie unter „Paginierte Antworten“.
Max. Feldtiefe
4
Bei der Ermittlung der Felder, die Sie anzeigen möchten, dürfen Sie sich nicht mehr als vier Ebenen vom abgefragten Objekt entfernen.
Max. Objektanzahl
50.000
Der Ergebnissatz darf nicht mehr als 50.000 primäre und sekundäre Objekte enthalten.
Max. Anzahl der Felder
1.000.000
Wenn der Ergebnissatz weniger als 50.000 Objekte umfasst, können die Ergebnisse maximal 1.000.000 Felder enthalten.
Max. Anzahl der Batch-Erstellungen/-Updates
100
Das maximale Limit für die Erstellung oder Aktualisierung von Batches ist 100.

Verwenden paginierter Antworten using-paginated-responses

Um die Abfragebeschränkung für die Standardanzahl der Ergebnisse zu überschreiben und 200 Ergebnisse zuzulassen, können Sie den Filter $$LIMIT=200 in Ihre Abfrage einbeziehen, wie im folgenden Beispiel gezeigt:

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

Um die Zuverlässigkeit und die Leistung anderer Mandanten im System sicherzustellen, beträgt die maximal zulässige Anzahl der Ergebnisse pro Abfrage 2.000 Objekte. Der Versuch, ein höheres Limit anzugeben, führt zu einer Fehlermeldung vom Typ IllegalArgumentException.

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 $$FIRST=200 im obigen Beispiel 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 Ergebnisse zurückgegeben werden.

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 Ergebnisse bei der Paginierung nicht wiederholt oder übersprungen werden. 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 bzw. eine Benutzerin mit der ID „abc123“ freigegeben wird, verwenden Sie die folgende Anfrage:

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

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

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

Verhalten von 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, hat es 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=New Project

Kopieren eines Objekts

Einige Objekte unterstützen das Kopieren. Für diese Objekttypen ist es möglich, neue Objekte durch Posten mit dem Parameter „copySourceID“ zu erstellen. Beispielsweise wird das angegebene Projekt mit der folgenden Anfrage kopiert und ein neuer Name für das Projekt festgelegt:

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": "4c7c08fa0000002ff924e298ee148df4"
}

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

Verhalten von PUT

PUT wird verwendet, um ein vorhandenes Objekt zu aktualisieren.

Die Antwort für eine PUT-Anfrage ist identisch mit der einer GET-Anfrage. 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 an Objekten werden immer nach ID unter Verwendung des 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=Neuer Projektname 
PUT /attask/api/v15.0/project?id=4c7…&name=Neuer Projektname

Angeben von JSON-Änderungen

Wie im folgenden Beispiel gezeigt, können Sie den Anfrageparameter „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“, 
     … 
}

Durchführen verschachtelter Aktualisierungen

Einige Objekte verfügen über private Sammlungen, die aktualisiert werden können. Im folgenden Beispiel wird beispielsweise veranschaulicht, wie die vorhandenen Arbeitsaufträge 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“
        } 
    ] 
}
NOTE
Aktualisierungen an der obersten Ebene sind zwar selten, aber Aktualisierungen an einer Sammlung oder einem verschachtelten Objekt ersetzen die vorhandene Sammlung vollständig. Um einen einzelnen Arbeitsauftrag für eine Aufgabe zu bearbeiten, ohne dass sich dies auf die Objekte auswirkt, verwenden Sie PUT für den Arbeitsauftrag und nicht für die Aufgabe.

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 Anfrageparameters „action“

Einige Objekte unterstützen weitere Aktionen, die zusätzlich zu einfachen Änderungen durchgeführt werden können. Diese Aktionen können Sie mit dem Anfrageparameter „action“ angeben. Mit der folgenden Anfrage wird beispielsweise die Timeline 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

Verschieben von Objekten

Im Folgenden wird die Syntax zum Verschieben einer Aufgabe von einem Projekt zu einem anderen 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

Nachfolgend 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/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx/share?accessorID=123abcxxxxxxxxxxxxxxxxxxxxxxxxxx&accessorObjCode=TEAMOB

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

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

Verhalten von DELETE

Mit DELETE wird ein Objekt entfernt. In jedem Fall kann der URI den Parameter „force=true“ enthalten, damit die angegebenen Daten und deren abhängige Elemente vom Server entfernt werden. 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

Mit einer Massenaktualisierungs-Anweisung werden mehrere Objekte gleichzeitig innerhalb eines einzigen API-Aufrufs aktualisiert. 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-cxxxxxxxxxxxxxxxxxxxxxxxxxx

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

data: [{
    ID: "53ff8d3d003b438b57a8a784df38f6b3",
    name: "Test_Project_1",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priority: 0,
    projectedCompletionDate: "2014-08-28T16:12:00:000-0400",
    status: "CUR"
},
{
    ID: "53ff8d49003b43a2562aa34eea3b6b10",
    name: "Test_Project_2",
    objCode: "PROJ",
    percentComplete: 0usi,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priority: 0,
    projectedCompletionDate: "2014-08-28T16:12:00:000-0400",
    status: "CUR"
}]

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

data: [ {
     ID: "53ff8e15003b461d4560f7f65a440078",
     name: "Test_Project_1_Edit",
     objCode: "PROJ",
     percentComplete: 0,
     plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
     plannedStartDate: "2014-08-28T11:00:00:000-0400",
     priority: 0,
     projectedCompletionDate: "2014-08-28T16:16:00:000-0400",
     status: "CUR"
},
{
    ID: "53ff8e19003b46238a58d303608de502",
    name: "Test_Project_2_Edit",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priority: 0,
    projectedCompletionDate: "2014-08-28T16:16:00:000-0400",
    status: "CUR"
}]
NOTE
Atomic-Batch-Vorgänge können nur „success: true“ oder einen Fehler zurückgeben.
recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43