Catalog -gegevens filteren met behulp van queryparameters

Als u de prestaties wilt verbeteren en relevante resultaten wilt ophalen, gebruikt u queryparameters om Catalog Service API-responsgegevens te filteren.

Leer meer over algemene filtermethoden voor Catalog -objecten in de API. Gebruik dit document naast de Gids van de Ontwikkelaar van de Catalogusvoor meer details op API interactie. Voor algemene Catalog Service informatie, zie het Catalog overzicht.

Teruggestuurde objecten beperken limit-returned-objects

De query-parameter limit beperkt het aantal objecten dat in een reactie wordt geretourneerd. Catalog reacties volgen vooraf gedefinieerde limieten:

API formaat

GET /{OBJECT_TYPE}?limit={LIMIT}

Verzoek

Het volgende verzoek wint een lijst van datasets terwijl het beperken van de reactie op drie voorwerpen terug.

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

Reactie

Een succesvolle reactie keert een lijst van datasets terug, die tot het aantal wordt beperkt door de limit vraagparameter wordt vermeld.

{
    "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"
    }
}

Weergegeven eigenschappen beperken limit-displayed-properties

Zelfs bij het filteren van het aantal objecten dat wordt geretourneerd met de parameter limit , kunnen de geretourneerde objecten zelf vaak meer informatie bevatten dan u eigenlijk nodig hebt. Als u de belasting van het systeem verder wilt verminderen, kunt u het beste reacties filteren en alleen de gewenste eigenschappen opnemen.

De properties -parameterfilters reageren op objecten om alleen een set opgegeven eigenschappen te retourneren. De parameter kan worden ingesteld om een of meerdere eigenschappen te retourneren.

De parameter properties kan alle objecteigenschappen op niveau accepteren. sampleKey kan worden geëxtraheerd met ?properties=subItem.sampleKey .

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

API formaat

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}

Verzoek

Het volgende verzoek wint een lijst van datasets terug. De door komma's gescheiden lijst met namen van eigenschappen die wordt geleverd onder de parameter properties geeft de eigenschappen aan die moeten worden geretourneerd in de reactie. Er wordt ook een parameter limit opgenomen die het aantal geretourneerde gegevenssets beperkt. Als de aanvraag geen parameter limit bevat, bevat de reactie maximaal 20 objecten.

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

Reactie

Een succesvol antwoord retourneert een lijst met Catalog -objecten waarbij alleen de gevraagde eigenschappen worden weergegeven.

{
    "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"
        }
    }
}

Op basis van bovenstaande reactie kan het volgende worden afgeleid:

Beginindex van verschuiving van reactielijst offset-starting-index

Met de query-parameter start verschuift u de lijst met reacties met een opgegeven getal door op nul gebaseerde nummering te gebruiken. start=2 verschuift bijvoorbeeld de reactie naar het begin van het derde weergegeven object.

Wanneer de parameter start niet aan een parameter limit is gekoppeld, is het maximale aantal geretourneerde objecten 20.

API formaat

GET /{OBJECT_TYPE}?start={OFFSET}

Verzoek

Het volgende verzoek wint een lijst van datasets terug, die aan het vijfde voorwerp (start=4) compenseren en de reactie beperken tot twee teruggekeerde datasets (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}'

Reactie

De reactie omvat een voorwerp JSON dat twee top-level punten (limit=2) bevat, voor elke dataset en hun details (details zijn versmald in het voorbeeld). De reactie wordt verschoven door vier (start=4), betekenend zijn de getoonde datasets aantal vijf en zes chronologisch.

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

Filteren op tag

Sommige catalogusobjecten ondersteunen het gebruik van een tags -kenmerk. Tags kunnen informatie aan een object koppelen en later worden gebruikt om dat object op te halen. De keuze van de tags die u wilt gebruiken en hoe u deze wilt toepassen, is afhankelijk van uw organisatieprocessen.

Er zijn enkele beperkingen waarmee u rekening kunt houden bij het gebruik van tags:

Hieronder ziet u een voorbeeld van een gegevensset die een eigenschap tags bevat. De tags binnen die eigenschap hebben de vorm van sleutel-waardeparen, waarbij elke tagwaarde wordt weergegeven als een array met één tekenreeks:

{
    "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 formaat

Waarden voor de parameter tags hebben de vorm van sleutel-waardeparen, die het formaat {TAG_NAME}:{TAG_VALUE} gebruiken. U kunt meerdere sleutelwaardeparen opgeven in de vorm van een lijst met komma's als scheidingsteken. Wanneer veelvoudige markeringen worden verstrekt, wordt een EN verhouding verondersteld.

De parameter steunt vervangingskarakters (*) voor markeringswaarden. Een zoektekenreeks van test* retourneert bijvoorbeeld een object waar de tagwaarde begint met 'test'. Een zoektekenreeks die alleen uit een jokerteken bestaat, kan worden gebruikt om objecten te filteren op basis van het feit of ze een specifieke tag bevatten, ongeacht de waarde ervan.

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}:*

Verzoek

Het volgende verzoek wint een lijst van datasets terug, filtrerend door één markering die een specifieke waarde EN de tweede markering die aanwezig is.

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

Reactie

Een succesvol antwoord retourneert een lijst met gegevenssets die sampleTag met de waarde "123456" EN secondTag bevatten, met een willekeurige waarde. Tenzij ook een limiet is opgegeven, bevat het antwoord maximaal 20 objecten.

{
    "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"
                ]
            },
    }
}

Filteren op datumbereik

Sommige eindpunten in de API van Catalog hebben vraagparameters die voor gerangschikte vragen, het vaakst in het geval van data toestaan.

API formaat

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

Verzoek

Met het volgende verzoek wordt een lijst opgehaald met batches die in de maand april 2019 zijn gemaakt.

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

Reactie

Een geslaagde reactie bevat een lijst met Catalog -objecten die binnen het opgegeven datumbereik vallen. Tenzij ook een limiet is opgegeven, bevat het antwoord maximaal 20 objecten.

{
    "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}",
    }
}

Sorteren op eigenschap

Met de parameter orderBy query kunt u reactiegegevens sorteren (ordenen) op basis van een opgegeven eigenschapswaarde. Deze parameter vereist een "richting" (asc voor het stijgen of desc voor het dalen), gevolgd door een dubbelepunt (:) en dan een bezit om de resultaten door te sorteren. Als er geen richting is opgegeven, wordt de standaardrichting oplopend.

U kunt meerdere sorteereigenschappen opgeven in een lijst met komma's als scheidingsteken. Als de eerste sorteereigenschap meerdere objecten produceert die dezelfde waarde voor die eigenschap bevatten, wordt de tweede sorteereigenschap gebruikt om die overeenkomende objecten verder te sorteren.

Neem bijvoorbeeld de volgende query: orderBy=name,desc:created . De resultaten worden in oplopende volgorde gesorteerd op basis van de eerste sorteereigenschap, name . Wanneer meerdere records dezelfde name -eigenschap delen, worden die overeenkomende records vervolgens gesorteerd op de tweede sorteereigenschap, created . Als geen geretourneerde records dezelfde name delen, wordt de sortering niet beïnvloed door de eigenschap created .

API formaat

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}

Verzoek

Met het volgende verzoek wordt een lijst opgehaald met gegevenssets die zijn gesorteerd op hun eigenschap name . Als om het even welke datasets het zelfde name delen, zullen die datasets beurtelings door hun updated bezit in dalende orde worden bevolen.

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

Reactie

Een geslaagde reactie bevat een lijst met Catalog -objecten die worden gesorteerd op basis van de parameter orderBy . Tenzij ook een limiet is opgegeven, bevat het antwoord maximaal 20 objecten.

{
    "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}",
    }
}

Filteren op eigenschap

Catalog biedt twee methoden voor het filteren op eigenschap, die nader worden beschreven in de volgende secties:

Eenvoudige filters gebruiken using-simple-filters

Met eenvoudige filters kunt u reacties filteren op basis van specifieke eigenschapswaarden. Een eenvoudig filter heeft de vorm van {PROPERTY_NAME}={VALUE}.

De query name=exampleName retourneert bijvoorbeeld alleen objecten waarvan de eigenschap name de waarde 'exampleName' bevat. Door contrast, keert de vraag name=!exampleName slechts voorwerpen terug het waarvan name bezit niet "exampleName" is.

Bovendien ondersteunen eenvoudige filters de mogelijkheid om te zoeken naar meerdere waarden voor één eigenschap. Wanneer de veelvoudige waarden worden verstrekt, keert de reactie voorwerpen terug het waarvan bezit om het even welk van de waarden in de verstrekte lijst aanpast. U kunt een multi-waardevraag omkeren door a ! karakter aan de lijst vooraf te bepalen, terugkerend slechts voorwerpen de waarvan bezitswaarde niet in de verstrekte lijst is (bijvoorbeeld, name=!exampleName,anotherName).

API formaat

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}

Verzoek

Het volgende verzoek wint een lijst van datasets terug, gefiltreerd om slechts datasets te omvatten de waarvan name bezit een waarde van "exampleName"of "anotherName"heeft.

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

Reactie

Een geslaagde reactie bevat een lijst met gegevenssets, exclusief gegevenssets waarvan name "exampleName" of "anotherName" is. Tenzij ook een limiet is opgegeven, bevat het antwoord maximaal 20 objecten.

{
    "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}",
    }
}

De parameter property gebruiken using-the-property-parameter

De query-parameter property biedt meer flexibiliteit voor op eigenschappen gebaseerde filtering dan eenvoudige filters. Naast het filtreren gebaseerd op of een bezit een specifieke waarde heeft, kan de property parameter andere vergelijkingsexploitanten (zoals "meer-dan" (>) en "minder-dan" (<)) evenals regelmatige uitdrukkingen gebruiken om door bezitswaarden te filtreren. Het kan ook filteren door of een eigenschap bestaat, ongeacht de waarde ervan.

Gebruik ampersand (&) om veelvoudige filters te combineren en uw vraag in één enkel verzoek te verfijnen. Wanneer u met meerdere velden filtert, wordt standaard een AND -relatie toegepast.

GET /datasets?property=id==abc123&property=name!=test

Wanneer u meerdere property -parameters in hetzelfde veld gebruikt, wordt alleen de laatst opgegeven parameter van kracht.

De parameter property kan alle objecteigenschappen op niveau accepteren. sampleKey kan worden gebruikt voor filtering met ?properties=subItem.sampleKey .

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

API formaat

GET /{OBJECT_TYPE}?property={CONDITION}

De waarde van de parameter property ondersteunt verschillende soorten voorwaardelijke expressies. In de volgende tabel wordt de basissyntaxis voor ondersteunde expressies beschreven:

Verzoek

Het volgende verzoek zal om het even welke datasets met een versieaantal groter dan 1.0.3 terugkeren.

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

Reactie

Een succesvolle reactie bevat een lijst met datasets waarvan de versienummers groter zijn dan 1.0.3. Tenzij ook een limiet is opgegeven, bevat het antwoord maximaal 20 objecten.

{
    "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}",
    }
}

Arrays filteren met de parameter property filter-arrays

Gebruik gelijkheids- en ongelijkheidsoperatoren om specifieke waarden op te nemen of uit te sluiten bij het filteren van resultaten op basis van array-eigenschappen.

Gelijkheidsfilters equality-filters

Als u een arrayveld met meerdere waarden wilt filteren, gebruikt u voor elke waarde afzonderlijke eigenschapparameters. Gebruik gelijkheidsfilters om alleen de items in de arraygegevens te retourneren die overeenkomen met de opgegeven waarden.

De voorbeeldquery hieronder geeft alleen resultaten van de array die zowel val1 als val2 bevat.

API formaat

GET /{OBJECT_TYPE}?property=arrayField=val1&property=arrayField=val2

Onkwaliteitsfilters inequality-filters

Gebruik ongelijkheidsoperatoren (!=) op een arrayveld om items in de gegevens uit te sluiten waar de array de opgegeven waarden bevat.

API formaat

GET /{OBJECT_TYPE}?property=arrayField!=val1&property=arrayField!=val2

Deze query retourneert documenten waarin arrayField niet val1 of val2 bevat.

Beperkingen van het filter Gelijkheid en ongelijkheid equality-inequality-limitations

U kunt niet zowel gelijkheid (=) als ongelijkheid (!=) op het zelfde gebied in één enkele vraag toepassen.