Filtrera Catalog-data med frågeparametrar

API:t Catalog Service tillåter att svarsdata filtreras med hjälp av frågeparametrar för begäran. En del av de bästa sätten för Catalog är att använda filter i alla API-anrop, eftersom de minskar belastningen på API:t och bidrar till att förbättra den övergripande prestandan.

Det här dokumentet innehåller de vanligaste metoderna för filtrering av Catalog-objekt i API:t. Vi rekommenderar att du refererar till det här dokumentet när du läser katalogutvecklarhandboken för att lära dig mer om hur du interagerar med Catalog API:t. Mer allmän information om Catalog Service finns i Catalog översikten.

Begränsa returnerade objekt

Frågeparametern limit begränsar antalet objekt som returneras i ett svar. Catalog svar mäts automatiskt enligt de konfigurerade gränserna:

API-format

GET /{OBJECT_TYPE}?limit={LIMIT}

Begäran

Följande begäran hämtar en lista med datauppsättningar samtidigt som svaret begränsas till tre objekt.

curl -X GET \
  https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3 \
  -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}'

Svar

Ett lyckat svar returnerar en lista med datauppsättningar, begränsad till det antal som anges av frågeparametern limit.

{
    "5ba9452f7de80400007fc52a": {
        "name": "Sample Dataset 1",
        "description": "Description of dataset.",
        "files": "@/dataSetFiles?dataSetId=5ba9452f7de80400007fc52a"
    },
    "5bb276b03a14440000971552": {
        "name": "Sample Dataset 2",
        "description": "Description of dataset.",
        "files": "@/dataSetFiles?dataSetId=5bb276b03a14440000971552"
    },
    "5bceaa4c26c115000039b24b": {
        "name": "Sample Dataset 3"
    }
}

Begränsa visade egenskaper

Även om du filtrerar antalet objekt som returneras med parametern limit kan de returnerade objekten ofta innehålla mer information än du faktiskt behöver. För att ytterligare minska belastningen på systemet är det bäst att filtrera svaren så att de bara innehåller de egenskaper som du behöver.

Parametern properties filtrerar svarsobjekt så att bara en uppsättning angivna egenskaper returneras. Parametern kan ställas in så att den returnerar en eller flera egenskaper.

Parametern properties kan acceptera alla nivåobjektsegenskaper. sampleKey kan extraheras med ?properties=subItem.sampleKey.

{
  "5ba9452f7de80400007fc52a": {
      "name": "Sample Dataset",
      "description": "Sample dataset containing important data",
      "subitem": {
          "sampleKey": "sampleValue"
      }
  }
}

API-format

GET /{OBJECT_TYPE}?properties={PROPERTY}
GET /{OBJECT_TYPE}?properties={PROPERTY_1},{PROPERTY_2},{PROPERTY_3}
GET /{OBJECT_TYPE}/{OBJECT_ID}?properties={PROPERTY_1},{PROPERTY_2},{PROPERTY_3}

Begäran

Följande begäran hämtar en lista med datauppsättningar. Den kommaavgränsade listan med egenskapsnamn som anges med parametern properties anger vilka egenskaper som ska returneras i svaret. En limit-parameter ingår också, vilket begränsar antalet returnerade datauppsättningar. Om begäran inte innehöll någon limit-parameter skulle svaret innehålla maximalt 20 objekt.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?limit=4&properties=name,schemaRef' \
  -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}'

Svar

Ett godkänt svar returnerar en lista med Catalog objekt där endast de begärda egenskaperna visas.

{
    "Dataset1": {
        "name": "Dataset 1",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/bc82c518380478b59a95c63e0f843121",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "Dataset2": {},
    "Dataset3": {
        "name": {},
    },
    "Dataset4": {
        "name": "Dataset 4",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Baserat på ovanstående svar kan man dra slutsatsen följande:

Startindex för förskjutning av svarslista

Frågeparametern start förskjuter svarslistan framåt med ett angivet nummer, med nollbaserad numrering. start=2 skulle till exempel förskjuta svaret så att det startar på det tredje listade objektet.

Om parametern start inte har parats med en limit-parameter är det maximala antalet returnerade objekt 20.

API-format

GET /{OBJECT_TYPE}?start={OFFSET}

Begäran

Följande begäran hämtar en lista med datauppsättningar, som förskjuts till det femte objektet (start=4) och begränsar svaret till två returnerade datauppsättningar (limit=2).

curl -X GET \
  https://platform.adobe.io/data/foundation/catalog/dataSets?start=4&limit=2 \
  -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}'

Svar

Svaret innehåller ett JSON-objekt som innehåller två objekt på den översta nivån (limit=2), ett för varje datauppsättning och deras information (detaljerna har konverterats i exemplet). Svaret ändras med fyra (start=4), vilket innebär att de datamängder som visas är nummer fem och sex kronologiskt.

{
    "Dataset5": {},
    "Dataset6": {}
}

Filtrera efter tagg

Vissa katalogobjekt stöder användningen av ett tags-attribut. Taggar kan bifoga information till ett objekt och sedan användas för att hämta objektet. Vilka taggar som ska användas och hur de ska användas beror på organisationens processer.

Det finns några begränsningar att tänka på när du använder taggar:

Nedan visas ett exempel på en datamängd som innehåller en tags-egenskap. Taggarna i den egenskapen har formen av nyckelvärdepar, där varje taggvärde visas som en array som innehåller en enda sträng:

{
    "5be1f2ecc73c1714ceba66e2": {
        "imsOrg": "{ORG_ID}",
        "tags": {
            "sampleTag": [
                "123456"
            ],
            "secondTag": [
                "sample_tag_value"
            ]
        },
        "name": "Sample Dataset",
        "description": "Same dataset containing sample data.",
        "createdUser": "{CREATED_USER}",
        "createdClient": "{CREATED_CLIENT}",
        "updatedUser": "{UPDATED_USER}",
        "version": "1.0.0",
        "created": 1541534444286,
        "updated": 1541534444286
    }
}

API-format

Värdena för parametern tags har formen av nyckelvärdepar med formatet {TAG_NAME}:{TAG_VALUE}. Flera nyckelvärdepar kan anges i form av en kommaavgränsad lista. När flera taggar anges antas en AND-relation.

Parametern stöder jokertecken (*) för taggvärden. En söksträng på test* returnerar till exempel alla objekt där taggvärdet börjar med "test". En söksträng som endast består av ett jokertecken kan användas för att filtrera objekt baserat på om de innehåller en viss tagg eller inte, oavsett dess värde.

GET /{OBJECT_TYPE}?tags={TAG_NAME}:{TAG_VALUE}
GET /{OBJECT_TYPE}?tags={TAG_NAME_1}:{TAG_VALUE_1},{TAG_NAME_2}:{TAG_VALUE_2}
GET /{OBJECT_TYPE}?tags={TAG_NAME}:{TAG_VALUE}*
GET /{OBJECT_TYPE}?tags={TAG_NAME}:*

Begäran

Följande begäran hämtar en lista med datauppsättningar, filtrerar efter en tagg med ett specifikt värde OCH den andra taggen finns.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?tags=sampleTag:123456,secondTag:* \
  -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}'

Svar

Ett lyckat svar returnerar en lista med datauppsättningar som innehåller sampleTag med värdet 123456, AND secondTag med valfritt värde. Om ingen gräns anges innehåller svaret högst 20 objekt.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 1",
            "created": 1533539550237,
            "updated": 1533539552416,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "tags": {
                "sampleTag": [
                    "123456"
                ],
                "secondTag": [
                    "Example tag value"
                ]
            },
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.0",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 2",
            "created": 1533539550237,
            "updated": 1533539552416,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "tags": {
                "sampleTag": [
                    "123456"
                ],
                "secondTag": [
                    "A different tag value"
                ],
                "anotherTag": [
                    "2.0"
                ]
            },
    }
}

Filtrera efter datumintervall

Vissa slutpunkter i API:t Catalog har frågeparametrar som tillåter intervallfrågor, oftast för datum.

API-format

GET /batches?createdAfter={TIMESTAMP_1}&createdBefore={TIMESTAMP_2}

Begäran

Följande begäran hämtar en lista över batchar som skapats under april 2019.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/batches?createdAfter=1554076800000&createdBefore=1556668799000' \
  -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}'

Svar

Ett godkänt svar innehåller en lista med Catalog objekt som ligger inom det angivna datumintervallet. Om ingen gräns anges innehåller svaret högst 20 objekt.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 1",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.0",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 2",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Sortera efter egenskap

Med frågeparametern orderBy kan du sortera (ordna) svarsdata baserat på ett angivet egenskapsvärde. Den här parametern kräver "direction" (asc för stigande eller desc för fallande), följt av kolon (:) och sedan en egenskap för att sortera resultaten efter. Om ingen riktning anges kommer standardriktningen att bli stigande.

Flera sorteringsegenskaper kan anges i en kommaseparerad lista. Om den första sorteringsegenskapen skapar flera objekt som innehåller samma värde för den egenskapen, används den andra sorteringsegenskapen för att ytterligare sortera de matchande objekten.

Ta till exempel följande fråga: orderBy=name,desc:created. Resultaten sorteras i stigande ordning baserat på den första sorteringsegenskapen, name. Om flera poster delar samma name-egenskap sorteras de matchande posterna sedan efter den andra sorteringsegenskapen, created. Om inga returnerade poster delar samma name räknas inte egenskapen created in i sorteringen.

API-format

GET /{OBJECT_TYPE}?orderBy=asc:{PROPERTY_NAME}
GET /{OBJECT_TYPE}?orderBy=desc:{PROPERTY_NAME}
GET /{OBJECT_TYPE}?orderBy={PROPERTY_NAME_1},desc:{PROPERTY_NAME_2}

Begäran

Följande begäran hämtar en lista med datauppsättningar sorterade efter deras name-egenskap. Om en datamängd delar samma name, kommer dessa datauppsättningar i sin tur att ordnas efter sin updated -egenskap i fallande ordning.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?orderBy=name,desc:updated' \
  -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}'

Svar

Ett godkänt svar innehåller en lista med Catalog objekt som är sorterade enligt parametern orderBy. Om ingen gräns anges innehåller svaret högst 20 objekt.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "0405",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.3",
            "imsOrg": "{ORG_ID}",
            "name": "AAM Dataset",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5cd3a129ec106214b722a939": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "AAM Dataset",
            "created": 1554028394852,
            "updated": 1554130582960,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Filtrera efter egenskap

Catalog innehåller två metoder för att filtrera efter egenskap, som beskrivs ytterligare i följande avsnitt:

Använda enkla filter using-simple-filters

Med enkla filter kan du filtrera svar baserat på specifika egenskapsvärden. Ett enkelt filter har formen {PROPERTY_NAME}={VALUE}.

Frågan name=exampleName returnerar till exempel bara objekt vars name-egenskap innehåller värdet "exampleName". Däremot returnerar frågan name=!exampleName bara objekt vars name-egenskap är inte "exampleName".

Dessutom har enkla filter stöd för att fråga efter flera värden för en enda egenskap. När flera värden anges returnerar svaret objekt vars egenskap matchar valfri av värdena i den angivna listan. Du kan invertera en fråga med flera värden genom att lägga till ett !-tecken i listan som prefix och bara returnera objekt vars egenskapsvärde är inte i den angivna listan (till exempel name=!exampleName,anotherName).

API-format

GET /{OBJECT_TYPE}?{PROPERTY_NAME}={VALUE}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}=!{VALUE}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}={VALUE_1},{VALUE_2},{VALUE_3}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}=!{VALUE_1},{VALUE_2},{VALUE_3}

Begäran

Följande begäran hämtar en lista med datauppsättningar, filtrerad så att den bara innehåller datauppsättningar vars name-egenskap har värdet "exampleName" eller "anotherName".

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?name=exampleName,anotherName' \
  -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}'

Svar

Ett godkänt svar innehåller en lista med datauppsättningar, exklusive datauppsättningar vars name är "exampleName" eller "anotherName". Om ingen gräns anges innehåller svaret högst 20 objekt.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "exampleName",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.3",
            "imsOrg": "{ORG_ID}",
            "name": "anotherName",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Använda parametern property using-the-property-parameter

Frågeparametern property ger större flexibilitet för egenskapsbaserad filtrering än enkla filter. Förutom filtrering baserad på om en egenskap har ett visst värde kan parametern property använda andra jämförelseoperatorer (till exempel"mer än" (>) och"mindre än" (<)) samt reguljära uttryck för att filtrera efter egenskapsvärden. Det kan också filtrera efter om en egenskap finns eller inte, oavsett dess värde.

Parametern property kan acceptera alla nivåobjektsegenskaper. sampleKey kan användas för filtrering med ?properties=subItem.sampleKey.

{
  "5ba9452f7de80400007fc52a": {
      "name": "Sample Dataset",
      "description": "Sample dataset containing important data",
      "subitem": {
          "sampleKey": "sampleValue"
      }
  }
}

API-format

GET /{OBJECT_TYPE}?property={CONDITION}

Värdet för parametern property stöder flera olika typer av villkorsuttryck. I följande tabell visas den grundläggande syntaxen för uttryck som stöds:

Begäran

Följande begäran returnerar alla datauppsättningar med ett versionsnummer som är större än 1.0.3.

curl -X GET \
  https://platform.adobe.io/data/foundation/catalog/dataSets?property=version>1.0.3 \
  -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}'

Svar

Ett godkänt svar innehåller en lista med datauppsättningar vars versionsnummer är större än 1.0.3. Om ingen gräns anges innehåller svaret högst 20 objekt.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.1.2",
            "imsOrg": "{ORG_ID}",
            "name": "sampleDataset",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.6",
            "imsOrg": "{ORG_ID}",
            "name": "exampleDataset",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5cd3a129ec106214b722a939": {
            "version": "1.0.4",
            "imsOrg": "{ORG_ID}",
            "name": "anotherDataset",
            "created": 1554028394852,
            "updated": 1554130582960,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Kombinera flera filter

Med ett et-tecken (&) kan du kombinera flera filter i en enda begäran. När ytterligare villkor läggs till i en begäran antas en AND-relation.

API-format

GET /{OBJECT_TYPE}?{FILTER_1}={VALUE}&{FILTER_2}={VALUE}&{FILTER_3}={VALUE}