Thing Batch API

The Thing Batch API is used to manage batches of things.

CREATE

Required role: ReadWrite
Required privilege: ThingBatches.CREATE on the specified domain

Creates a number of things and corresponding thing certificates by creating a batch that is processed in the background. For convenience all certificates in a batch is also zipped as one archive to make it easier to get.

API Endpoint: [POST]: /thingbatches

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Body

• thingType: The id of the thing type that the created things should belong to. required
• domain: The id of the domain that the created things should belong to. required
• requestedSize: The number of things to create. required
• concurrency: The number of things that should be created at the same time.
• protocol: The protocol to connect the things
• identityCodes: A list of unique identity codes. The size of this list should be equal to requestedSize

Example payload

{
    "thingType": "1",
    "domain": "root",
    "requestedSize": 2,
    "protocol": "iotgw",
    "identityCodes": [{"imsi": "123", "imei": "1234"}, {"imsi": "234", "imei": "2345"}]
}

Response

• batchId: The id of the batch that will create the things.

Errors

Key	Params	Property	Description
NOT_AUTHORIZED_DOMAIN		domain	Returned if the user tries to create a thing on a domain that the user is not authorized to see.
PROPERTY_NOT_A_NUMBER		requestedSize	Returned if the requested size was not a number.
PROPERTY_NOT_IN_RANGE	min, max	requestedSize	Returned if the requested size was not between 1 and 1000.
PROPERTY_REQUIRED		domain	Returned if no domain was provided.
PROPERTY_REQUIRED		requestedSize	Returned if no requested size was provided.
PROPERTY_REQUIRED		thingType	Returned if no thing type was provided.
INVALID_ARGUMENTS		thingType	Returned if the thing type id does not fulfil the thing type id pattern requirements
THING_TYPE_NOT_FOUND		thingType	Returned if the thing type does not exist

LIST

Required role: ReadWrite
Required privilege: ThingBatches.CREATE on the home domain of the calling user

Lists metadata for all thing batches for a specific thing type, including a download url for generated thing credentials.

Note: There is no paging functionality, only the first page is delivered from an alphabetically sorted file list. The page contents are then sorted by batch property finishedAt descending, leaving ev. unfinished bathes on top. In order to get the latest batches, the batch file names needs to have a timestamp following the prefix eg. batch-${thingTypeId}-${createdAtTimestamp}.

API Endpoint: [POST]: /thingbatches/list

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Body

• maxKeys: The maximum number of files to get (default 1000).
• prefix: A name prefix that all files in the response must have. This property should target the batch name pattern used for the thing type.
• filter
  • domains: An array of domain ids that, if specified, is used to limit the list of thing batches.
  • thingTypes: An array of thing type ids that, if specified, is used to limit the list of thing batches.
  • freeTexts: An array of any non-empty text that, if specified, is used to limit the list of thing batches.

Example payload

{
    "prefix": "batch-${thingTypeId}-",
    "maxKeys": 100
}

Response

• isTruncated: false if all files that matched the search criteria is included in the result, true otherwise.
• name: The full name of the bucket.
• prefix: The prefix that was used to get the files. optional
• maxKeys: The maximum number of files that was returned.
• encodingType: The encoding type used to encode file names in the response. (url)
• files[]: A list of files matching the search criteria sorted by time the batch finished, with batches currently under processing on top.
  • url: The full url to use to access the thing credentials archive file for the things created by the batch job. Only present if the batch has completed successfully. optional
  • batchId: Name of the related create thing batch job.
  • currentSize: Current size (number of things) of the related create thing batch. This represents the number of things created so far by the batch job.
  • requestedSize: Requested size (number of things) of the related create thing batch.
  • concurrency: The concurrency for the related create thing batch job, ie. the number of things that should be created at the same time. Default is 5.
  • attributes: Attributes of the related create thing batch job:
    • thingType: The thingType of the things in the related create thing batch job.
    • domain: The domain of the things in the related create thing batch job.
    • createdBy: Name of the user that created the thing batch job.
  • createdAt: The time when the create thing batch job was created.
  • finishedAt: The time when the create thing batch job finished. optional

Errors

Key	Params	Property	Description
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.