Appendice alla guida API Catalog Service

16 luglio 2024

Creato per:

  • Sviluppatore

Questo documento contiene informazioni aggiuntive utili per l'utilizzo dell'API Catalog.

Visualizzare oggetti correlati

Alcuni oggetti Catalog possono essere correlati con altri oggetti Catalog. Tutti i campi con prefisso @ nei payload di risposta indicano gli oggetti correlati. I valori per questi campi assumono la forma di un URI, che può essere utilizzato in una richiesta di GET separata per recuperare gli oggetti correlati che rappresentano.

Il set di dati di esempio restituito nel documento in ricerca di un set di dati specifico contiene un campo files con il seguente valore URI: "@/datasetFiles?datasetId={DATASET_ID}". È possibile visualizzare il contenuto del campo files utilizzando questo URI come percorso per una nuova richiesta GET.

Formato API

GET {OBJECT_URI}
ParametroDescrizione
{OBJECT_URI}URI fornito dal campo oggetto intercorrelato, escluso il simbolo @.

Richiesta

La richiesta seguente utilizza l’URI fornito con la proprietà files del set di dati di esempio per recuperare un elenco dei file associati al set di dati.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets/datasetFiles?datasetId={DATASET_ID}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce un elenco di oggetti correlati. In questo esempio viene restituito un elenco di file di set di dati.

{
    "7d501090-0280-11ea-a6bb-f18323b7005c-1": {
        "id": "7d501090-0280-11ea-a6bb-f18323b7005c-1",
        "batchId": "7d501090-0280-11ea-a6bb-f18323b7005c",
        "dataSetViewId": "5ba9452f7de80400007fc52b",
        "imsOrg": "{ORG_ID}",
        "createdUser": "{USER_ID}",
        "createdClient": "{CLIENT_ID}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1573256315368,
        "updated": 1573256315368
    },
    "148ac690-0280-11ea-8d23-8571a35dce49-1": {
        "id": "148ac690-0280-11ea-8d23-8571a35dce49-1",
        "batchId": "148ac690-0280-11ea-8d23-8571a35dce49",
        "dataSetViewId": "5ba9452f7de80400007fc52b",
        "imsOrg": "{ORG_ID}",
        "createdUser": "{USER_ID}",
        "createdClient": "{CLIENT_ID}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1573255982433,
        "updated": 1573255982433
    },
    "64dd5e19-8ea4-4ddd-acd1-f43cccd8eddb-1": {
        "id": "64dd5e19-8ea4-4ddd-acd1-f43cccd8eddb-1",
        "batchId": "64dd5e19-8ea4-4ddd-acd1-f43cccd8eddb",
        "dataSetViewId": "5ba9452f7de80400007fc52b",
        "imsOrg": "{ORG_ID}",
        "createdUser": "{USER_ID}",
        "createdClient": "{CLIENT_ID}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1569499425037,
        "updated": 1569499425037
    }
}

Intestazioni di richiesta aggiuntive

Catalog fornisce diverse convenzioni di intestazione che consentono di mantenere l'integrità dei dati durante gli aggiornamenti.

If-Match

È consigliabile utilizzare il controllo delle versioni degli oggetti per evitare il tipo di danneggiamento dei dati che si verifica quando un oggetto viene salvato da più utenti quasi contemporaneamente.

La best practice per aggiornare un oggetto prevede innanzitutto una chiamata API per visualizzare (GET) l’oggetto da aggiornare. Contenuto nella risposta (e in qualsiasi chiamata in cui la risposta contiene un singolo oggetto) è un'intestazione E-Tag contenente la versione dell'oggetto. Se si aggiunge la versione dell'oggetto come intestazione di richiesta denominata If-Match nelle chiamate di aggiornamento (PUT o PATCH), l'aggiornamento avrà esito positivo solo se la versione è ancora la stessa, evitando conflitti di dati.

Se le versioni non corrispondono (l’oggetto è stato modificato da un altro processo dopo averlo recuperato), riceverai lo stato HTTP 412 (Precondizione non riuscita) che indica che l’accesso alla risorsa di destinazione è stato negato.

Pragma

In alcuni casi, può essere utile convalidare un oggetto senza salvare le informazioni. L'utilizzo dell'intestazione Pragma con un valore di validate-only consente di inviare richieste POST o PUT solo a scopo di convalida, impedendo la persistenza di eventuali modifiche ai dati.