DC 5.9 Getting assets by other properties

URL: /digizuitecore/legacyservice/api/assets/search

Method: POST

Auth required: YES

 

The search API is extremely flexible in what it can search for, so this page only demonstrates a couple of examples to show the general structure of achieving different results.

You can only get the first 10.000 results by paging through the result using the skip parameter. If you need more, you should use a cursor approach instead. The general trick in the cursor approach is to sort by asset id, then keep track of the last asset id you saw, and request all the assets with an asset id larger/smaller than that. This is very fast and allows you to get all results without missing anything in case the result set changes midway through.

 

Request properties

Name

Type

Example

Description

Name

Type

Example

Description

sortBy

array of object

 

Specifies how you want results sorted. Multiple items can be passed in the array to specify sorting criteria in case 2 assets have the same value.

sortBy.searchKey

string

assetId

The key of the search field you want to sort on

sortBy.order

enum/string, one of

  • Ascending

  • Descending

Ascending

The order you want results sorted in.

facetFields

array of object

 

Specifies how you want to query for specific value, or how you want faceting results for a UI.

facetFields.searchKey

string

assetId

The key of the search field you want to execute this facet on.

facetFields.search

string

cat

If you are requesting faceting for this field and not just filtering, then this can be used to search in the facet results instead, in case the value you are looking for is not in the top 10.

facetFields.values

array of string

["123", "456"]

Will filter the assets in the result to include this value. Assets that doesn’t have this value will be excluded from the result set.

facetFields.excluded

array of strings

["789"]

Will filter the assets in the result to only include assets that doesn’t have this value. If both excluded and values are specified, excluded takes presidence when deciding if an asset should be in the result or not.

facetFields.operation

enum/string, one of

  • Or

  • And

Or

If multiple values are specified, is it required that the asset has all the value (And), or only 1 of them (Or).

facetFields.longRange

object

 

If the field you are faceting on is number-like, this can be used to search for assets with a value in the given range.

facetFields.longRange.from

int64/long

42

All assets has to have a value greater than or equals to this.

facetFields.longRange.to

int64/long

896

All assets has to have a value less than or equals to this.

facetFields.doubleRange

object

 

If the field you are searching is a float field, this to be used to search for assets with a value in the given range.

facetFields.doubleRange.from

double

42.5

All assets has to have a value greater than or equals to this.

facetFields.doubleRange.to

double

896.33

All assets has to have a value less than or equals to this.

facetFields.dateRange

object

 

If the field you are searching is a datetime field, this to be used to search for assets with a value in the given range.

facetFields.dateRange.from

datetime

2023-07-03T00:00:00.000

All assets has to have a value greater than or equals to this.

facetFields.dateRange.to

datetime

2023-07-07T00:00:00.000

All assets has to have a value less than or equals to this.

facetFields.facetMode

enum/string, one of

  • Facet

  • QueryOnly

 

Used to control if facet values are calculated. If you don’t need to render facets in the UI, send QueryOnly for better performance.

facetFields.recursive

bool

true or false

If the field you are searching on is tree like, for example tree metafields or channelFolder, this can be used to control if we are only searching for directly that value, or in all “children” of that value too.

facetFields.missingValueHandling

enum/string, one of

  • Irrelevant

  • OnlyShowEmpty

  • HideEmpty

 

How to deal with assets without a value in the field.

  • Irrelevant: If the value is missing or not doesn’t matter.

  • OnlyShowEmpty: Only assets without a value in the field will be shown. Is mutually exlusive with values and excluded

  • HideEmpty: Only assets that has a value in the field is included in the search results. Implied if values is specified.

 

facetFields.doubleExactSearchRange

double

0.01

If doubleRange.from and doubleRange.to is specified to the same value, this can be used to control how exact the equality operation is.

facetFields.facetCounts

int

10

How many facet values to return when facetMode is set to facet.

metaFieldItemGuids

array of string/guid/uuid

6afe78b7-3f24-49f3-bf95-24890ea62696

Additional metadata that should be included in the asset response. See Get Assets for more information.

freeText

string

cat|dog

Freetext searches on assets. The specifc fields that will be searches on can be controlled using freeTextOnFields.

freeTextOnFields

array of string

6afe78b7-3f24-49f3-bf95-24890ea62696

The search keys of the fields to execute freetext search on.

If not specified the system will search in all text-like fields. If the search value is a valid integer, then assetId and itemId will also be search.

defaultFreeTextOperation

enum/string, one of

  • Or

  • And

and

If there is a space in the freetext query, does that imply and or or between the value. Recommend value is and.

count

int

12

How many assets to include in the result.

skip

int

0 or 100

How many assets in the result to skip before returning. Can be used to implement paging.

calculateTrueCount

bool

false or true

If you have more than 10000 matching assets in the result, you will get a total of 10000. If you pass true here, the actual true total number of matching assets will be calculated.

 

Response properties

Name

Type

Description

Name

Type

Description

errorCode

int

The status code in case something went wrong.

errorMessage

string

An error message in case something wen’t wrong.

hasError

bool

If something went wrong, this will be true.

items

array of objects

Same structure as the Get assets response

total

int

The number of assets that matches the search.

totalRelation

enum/string, one of

  • Eq

  • Gte

Is the total number actually equal to the number of search results. eq means total matches the number of results. Gte means there are more results than the total shows.

facets

array of object

Any facetRequest fields that have FacetMode=Facet will be returned here. Again the type property should be check to ensure you parse them as the correct subtype.

facets.searchKey

string

The searchkey that was passed in the request. Use it to map between request and response.

facets.fieldName

string

The display name of this search field.

facets.buckets

list of objects

Each bucket is a “facet value”.

facets.buckets.key

string

The value to pass in facetFields.values/excluded to search/exclude this value in the result.

facets.buckets.count

int

How many assets has this value.

facets.buckets.label

string/null

A text value to display for this bucket.

facets.buckets.valueObject

object

A details object for this value. For combo value fields this will be the combo value itself. For tree fields the tree value. For ItemReference field this is the item.

facets.min

long/double/datetime/null

The minimum value that occurs for all the assets matching the search.

facets.max

long/double/datetime/null

The maximum value that occurs for all the assets matching the search.

trueTotal

int

If calculateTrueCount was specified, then this contains the actual number of matches.

 

This will simply get the first 12 assets you have access to, sorted by asset id ascending. It will not include any additional facet information.

POST https://<my-dam>/digizuitecore/legacyservice/api/assets/search Authorization: AccessKey MIIC...o0Y= Content-Type: application/json { "count": 12, "skip": 0 }

 

This will get assets you have access to, that are in the specific channel folder, or any children of that channel folder.

POST https://<my-dam>/digizuitecore/legacyservice/api/assets/search Authorization: AccessKey MIIC...o0Y= Content-Type: application/json { "facetFields": [ { "facetMode": "QueryOnly", "searchKey": "channelFolder", "values": [ "126" ], "recursive": true } ], "count": 12, "skip": 0 }

 

POST https://<my-dam>/digizuitecore/legacyservice/api/assets/search Authorization: AccessKey MIIC...o0Y= Content-Type: application/json { "facetFields": [ { "searchKey": "6afe78b7-3f24-49f3-bf95-24890ea62696", "operation": "Or", "recursive": false, "values": [ "50178" ] } ], "count": 12, "skip": 0 }