A2v10 Platform documentation
UK


Working with binary objects (blob)

Data models

General information

A binary object (this can be an image, attachment, etc.) is a separate entity. It has the Name, Mime properties and, actually, data (Stream).

This entity can be stored in a separate table for each item, as well as in a common table of attachments with an additional table of relations. An access token generation mechanism is used to prevent unauthorized access to attachments. A token is simply a hash of a string containing the ID of the current session, the user ID, and the additional access key (guid) associated with that attachment. The simplest way is to add this key as a field with a uniqueidentifier type and a default newid() value.

Working with binary objects actually consists of three almost independent parts.

  1. Obtaining the object itself and the access token. Here everything is simple and you can use the standard tools of the platform. However, you will not be able to download the data stream immediately. We need some separate tools to work with this stream. The simplest option is to download the data by clicking on the link. If we work with pictures, it makes sense to show their Preview. In addition, an access token must be generated to prevent unauthorized access. To do this, you have to include a field with the special !Token. type into the recordset. When processing this field, the system will take a value (this will be guid) and generate an access token instead. Note that the values of this token will be different in different browser sessions.
  2. Receiving bytes from the server (pictures, attachments) using an access token. Used to display images (Image, FileImage items) or simply to load them using the File command.
  3. Uploading data to the server. You can save data anywhere (for example in a database or in Azure Storage). This attachment has an ID. It can be used to obtain content for downloading or displaying binary data (picture, file). Note that this ID will be recorded into the model itself only when the model is saved. In addition to the download ID, an access token will be generated when the data is saved. It also has to be recorded into the model (you don't need to save it; when loading, it will be newly generated anyway). Note that this ID will only be written to the model itself when the model is saved. In addition to the download ID, an access token will be generated when the data is saved. It also has to be recorded into the model (you don’t need to save it; when loading it will be newly generated anyway).

Stored procedure formats

Two stored procedures are used to work with binary data. One for reading data (.Load suffix), another for their recording (.Update suffix). Note that the procedures for working with binary data are specific and do not comply with the rules for building models.

.Load Procedure

The procedure receives the following parameters (the names are fixed, the order does not matter):

  • @TenantId int - tenant ID (only in a multitenant environment).
  • @UserId bigint - current user ID.
  • @Id bigint - data (image, attachment) ID.

The procedure must return a single record set with the following fields (field names matter, their order is arbitrary).

  • Id bigint - data (image, attachment) ID.
  • Mime nvarchar(255) - mime data type.
  • Name nvarchar(255) - the recordset name.
  • Stream varbinary(max) - the data stream itself. Can be equal to null.
  • BlobName nvarcvhar(max) - the name of the set in external storage (e. g. Azure Storage). Can be equal to null.
  • Token uniqueidentifier - the field for generating the access token. This item must correspond to what the load procedure of the model, from which this data will be received, will return.

The download procedure must return one of the fields BlobName or Stream. If the BlobName field is specified, the data will be retrieved from external storage (Azure Storage) and the value of the Stream field will be ignored.

.Update Procedure

The procedure receives the following parameters (the names are fixed, the order does not matter):

  • @TenantId int - tenant ID (only in a multitenant environment).
  • @UserId bigint - current user ID.
  • @Name nvarchar(255) - the recordset name.
  • @Mime nvarchar(255) - mime data type.
  • @Stream varbinary(max) - the data stream itself or null, if the data is stored in external storage.
  • @BlobName nvarcvhar(max) - the set name in external storage or null.

The procedure must return a single set with the following fields (field names matter, order not important).

  • Id bigint - data (image, attachment) ID.
  • Token uniqueidentifier - field for generating the access token.

The data returned by this procedure will be returned to the client, who will need to add it to their data model.

See also