Nozioni di base sulle API di Adobe Workfront Planning

L’obiettivo per l’API di pianificazione di Adobe Workfront è semplificare la creazione di integrazioni con Planning introducendo un’architettura REST-ful che funziona tramite HTTP. Questo documento presuppone che tu abbia familiarità con le risposte REST e JSON e descrive l’approccio adottato dall’API di Planning.

La familiarità con lo schema di Workfront Planning consente di comprendere le relazioni tra i database che possono essere utilizzate per estrarre i dati da Workfront Planning a scopo di integrazione.

Puoi richiamare l’API di pianificazione da un campo di ricerca Esterna in un modulo personalizzato Workfront.

Per ulteriori informazioni sui campi di ricerca esterna, vedere Esempi di campi di ricerca esterna in un modulo personalizzato.

URL API di Workfront Planning

Operazioni

Gli oggetti vengono manipolati inviando una richiesta HTTP al relativo URI univoco. L'operazione da eseguire è specificata dal metodo HTTP.

I metodi HTTP standard corrispondono alle operazioni seguenti:

Per ulteriori dettagli ed esempi di ciascuna operazione, vedere la documentazione per gli sviluppatori API di Workfront Planning.

Tipi di campi e modificatori di ricerca utilizzati con tali campi

È possibile utilizzare modificatori e filtri con i campi per controllare quali dati verranno restituiti nei risultati.

Utilizzo dei modificatori di ricerca

Workfront Planning supporta i seguenti modificatori di ricerca:

Tipi di campo

Di seguito è riportato l’elenco dei tipi di campo supportati e i modificatori di ricerca che è possibile utilizzare con ciascuno di questi tipi di campo

Utilizzo delle istruzioni "And" e "Or"

Nella chiamata API è possibile avere filtri basati su diversi criteri combinati da istruzioni $and" e "$or"

{
  "recordTypeId": "recordTypeId",
  "offset": "integer",
  "limit": "integer",
  "filters": [
    {
      "$or": [
        {
          "launch_date": {
            "$isBetween": [
              "2024-03-31T20:00:00.000Z",
              "2024-04-01T20:00:00.000Z"
            ]
          }
        },
        {
          "$and": [
            {
              "launch_date": {
                "$isBetween": [
                  "2024-03-31T20:00:00.000Z",
                  "2024-04-01T20:00:00.000Z"
                ]
              }
            },
            {
              "status": "active"
            }
          ]
        },
        {
          "$and": [
            {
              "launch_date": {
                "$isBetween": [
                  "2024-04-15T00:00:00.000Z",
                  "2024-04-16T00:00:00.000Z"
                ]
              }
            },
            {
              "status": "planned"
            }
          ]
        }
      ]
    }
  ]
}

Utilizzo del parametro della richiesta fields

Puoi utilizzare il parametro di richiesta fields per specificare un elenco separato da virgole di campi specifici da restituire. Questi nomi di campo fanno distinzione tra maiuscole e minuscole.

Ad esempio, la richiesta

/v1/records/search?attributes=data,createdBy

{
    "records": [
        {
            "id": "Rc6527ecb35df57c441d92ba00",
            "createdBy": "61a9cc0500002f9fdaa7a6f824f557e1",
            "createdAt": null,
            "updatedBy": null,
            "updatedAt": null,
            "customerId": null,
            "imsOrgId": null,
            "recordTypeId": null,
            "data": {
                "F666c0b58b6fee61a2ea6ea81": [
                    {
                        "externalId": null,
                        "id": "Rc665728ff95730b58bc757b13",
                        "value": null
                    },
....

restituisce una risposta simile alla seguente:

{
    "priority": 2,
    "name": "first task",
    "ID": "4c7c08fa0000002ff924e298ee148df4",
    "plannedStartDate": "2010-08-30T09:00:00:000-0600"
}

Ordinamento dei risultati della query nell’API

Puoi ordinare i risultati in base a qualsiasi campo se aggiungi quanto segue alla chiamata API:

/v1/records/search

Corpo della richiesta:

{
    "recordTypeId": "Rt6527ecb25df57c441d92b9fa",
    "filters": [],
    "sorting": [
        {
            "fieldId": "F6527ecb25df57c441d92b9fc",
            "direction": "asc"
        },
        {
            "fieldId": "F658afcbd4a0273c67c346fd5",
            "direction": "desc"
        }
    ],
    "limit": 500,
    "offset": 0,
    "rowOrderViewId": "V6527ecb75df57c441d92ba03",
    "groupingFieldIds": []
}

Limiti delle query e risposte impaginate

Per impostazione predefinita, le richieste API di Planning restituiscono 500 risultati, a partire dall’inizio dell’elenco. Per ignorare il limite predefinito per il numero di risultati, è possibile utilizzare il parametro limit nelle richieste e impostarlo su un numero diverso, fino a 2.000 risultati.

È consigliabile considerare l'utilizzo di risposte impaginate per set di dati di grandi dimensioni aggiungendo il parametro offset alle richieste. Le risposte impaginate consentono di specificare la posizione del primo risultato che deve essere restituito.

Ad esempio, se si desidera restituire i risultati 2001-4000, è possibile utilizzare la seguente richiesta. In questo esempio vengono restituiti 2000 record con stato attivo, a partire dal risultato 2001:

POST /v1/records/search

Corpo della richiesta:

{
    "recordTypeId": "recordTypeId",
    "offset": "2001",
    "limit": "2000",
    "filters": [
        { "status": "active" }
    ]
}

Per assicurarti che i risultati siano impaginati correttamente, utilizza un parametro di ordinamento. Questo consente di restituire i risultati nello stesso ordine, in modo che l’impaginazione non si ripeta né salti i risultati.

Per ulteriori informazioni sull'ordinamento, vedere Ordinamento dei risultati della query nell'API in questo articolo.