Bases d’API

Utiliser les paramètres du filtre

L’un des inconvénients potentiels de l’utilisation de paramètres URL pour les filtres de recherche est que Workfront analyse certains paramètres avant de vérifier les différentes méthodes d’authentification (par exemple, nom d’utilisateur ou d’utilisatrice, mot de passe, apiKey, cookie). Dans ce cas, les paramètres ne sont pas utilisés comme filtres dans l’appel.

Pour éviter ce problème, vous pouvez placer ces valeurs dans des paramètres de filtre avec un formatage JSON. Par exemple, si vous voulez filtrer le nom d’utilisateur ou d’utilisatrice testuser, au lieu d’utiliser

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

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

Utiliser le paramètre de requête Map

Par défaut, les données renvoyées par une recherche sont sous la forme d’un tableau JSON. Selon votre cas d’utilisation, il peut être plus efficace d’obtenir le résultat sous la forme d’un objet JSON indexé par ID. Pour ce faire, il convient d’utiliser le paramètre de requête Map. Par exemple, la requête

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

Rechercher plusieurs champs imbriqués

Par défaut, seuls le nom et l’ID de chaque tâche sont renvoyés, mais des champs imbriqués supplémentaires peuvent être spécifiés à l’aide de la syntaxe des deux points. Pour afficher tous les champs disponibles pour un objet ou une collection connexe, il suffit d’ajouter deux points et un astérisque à la référence de l’objet ou de la collection.

/attask/api/v15.0/task/search?fields=assignments:*

Récupérer des données personnalisées

Vous pouvez récupérer des champs de données personnalisés en utilisant le préfixe « DE: ». Par exemple, pour demander un projet avec un paramètre appelé « CustomText », utilisez la requête suivante :

/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"] 
    } 
}

Utiliser les requêtes nommées

Certains types d’objets ont des recherches nommées qui sont couramment exécutées et sont disponibles en ajoutant le nom de la requête à la fin de l’URI du type d’objet. Par exemple, la requête suivante permet de récupérer les éléments de travail (tâches et problèmes) qui sont actuellement affectés à l’utilisateur ou l’utilisatrice :

/attask/api/v15.0/work/myWork

Utiliser les réponses paginées

Pour passer outre la limite du nombre de résultats par défaut et autoriser 200 résultats, vous pouvez inclure le filtre $$LIMIT=200 dans votre requête, comme dans l’exemple suivant :

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

Pour garantir la fiabilité et les performances des autres clientes et clients du système, la limite maximale des résultats autorisés par requête est de 2 000 objets. Toute tentative de spécifier une limite plus importante entraîne un message d’erreur IllegalArgumentException.

Par conséquent, nous vous recommandons d’utiliser des réponses paginées pour les jeux de données volumineux. Pour spécifier le premier résultat à renvoyer, ajoutez le filtre $$FIRST. Par exemple, la demande suivante renvoie les résultats 201-250 pour une requête :

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

Notez que dans l’exemple ci-dessus, $$FIRST=200 renvoie le 201e résultat. $$FIRST=0 renverrait le premier résultat. Il peut être utile de considérer la valeur $$FIRST comme le nombre de résultats que vous souhaitez ignorer avant de renvoyer les résultats.

Pour vous assurer que vos résultats sont correctement paginés, utilisez un paramètre de tri. Cela permet de renvoyer les résultats dans le même ordre, de sorte que la pagination ne répète pas ou n’ignore pas de résultats. Par exemple, pour trier à l’aide de l’ID de l’objet, utilisez ID_Sort=asc.

Utiliser le paramètre de requête Action

Certains objets permettent d’effectuer des actions supplémentaires, en plus des simples modifications. Vous pouvez spécifier ces actions à l’aide du paramètre de requête Action. Par exemple, la requête suivante recalcule la chronologie d’un projet donné :

PUT /attask/api/v15.0/project/4c7...?action=calculateTimeline

or

PUT /attask/api/v15.0/project/4c7.../calculateTimeline 

Déplacer des objets

La syntaxe suivante permet de déplacer une tâche d’un projet à un autre :

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

Voici un exemple de chaque type d’action :

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

Partager des objets

La syntaxe suivante permet de partager un projet avec une équipe :

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