Media Services
- Morten Lindequist Køhler
- Zoltan Mikolas
- Jan Wisén Francke-Larsen
The media services consist of services which allows retrieving images and files, collectively called Binaries, out of Perfion. The Media Services API is hosted on a Microsoft IIS Web Server. The services are designed according to a pull-strategy such that it scales linearly.
The media services consist of the following services:
Service name | Description |
File | Binary file service. Serves Perfion file and image type binaries, but does not allow any image processing. The service will only deliver the original file content and it has an option to either show file content in line (e.g. in internet browser) or define it as an attachment which will force users to download the file instead of rendering file content inline. Any requested files will be saved in a cache and the service will use the cached file next time the same request is sent. |
Image | Binary image service. Serves Perfion file and image type binaries and allows image processing. Image processing is possible only when using Perfion image type binaries. The image service will serve Perfion file type binaries, but such binaries will be served as if they were requested via the File service. This means that image processing is not supported for such requests. The service has an option to either show file content inline (e.g. in a browser) or stream the content as an attachment available for download. Any processed images will be saved in a cache and the service will use the cached file next time the same request is sent. The image service can optionally add watermark to the images based on configuration and the request parameters. Please refer to the Image Watermarking section for more details. |
Watermarked Image | The Watermarked Image service works similar to the Image service, with the exception that it adds watermark to all served images and that it only will serve image type binaries. As file type binaries cannot have watermarks applied to them, the Watermarked service will not service such requests. |
UncachedImage | The Uncached Image service works similar to the Image service with the exception that it will not use any precached renditions. |
NOTE: The ability for a file or an image content to be rendered inline depends on the ability of the application which renders the response from media services. In most cases such application will be an internet browser. Most internet browsers can render images inline. An exception could be that it will not render more complicated image formats such as TIFF. Most internet browsers will also render some of the file formats inline, e.g. if it is a text, HTML or XML file.
Media Service Configuration
Media services have several parameters which may be set to change its behavior. The configuration parameters can be specified in several ways:
Web.Config file. The “appSettings” element of the Web.Config file is used to add media services parameters and “connectionStrings” element is used when defining connection string to Perfion database.
MediaService.Config file. This configuration file is optional, but if defined, then all media services parameters will be used from this file instead of using Web.Config file.
NOTE: The use of Web.Config file to specify media services parameters is used for backwards compatibility to support previous versions of media services. It is recommended to use MediaService.Config file instead.
The table below shows all parameters supported by media services. Note that all parameter names are based on how they are defined in MediaService.Config file. The equivalent parameter names are also provided for Web.Config file in parameter descriptions.
Parameter name | Description |
ID | Media service ID. The parameter is optional for database based media service and required for Perfion Cloud based media service. The ID is a standard GUID identifier, e.g. ‘8e118ad2-70eb-430f-8cd0-ca9a8408f897’. Parameter key in Web.Config file: Perfion.MediaServiceId |
Name | Media services name. Optional parameter. Used only with Perfion Cloud based media service. Parameter key in Web.Config file: Perfion.MediaServiceName |
IsActive | Boolean parameter which defines if the media service is enabled. Parameter key in Web.Config file: Perfion.IsActive. It is optional for Web.Config and if not define will have a default value ‘true’, e.g. the media service is enabled. |
PerfionDBConnectionString | Connection string of Perfion database. Used only with database based media services. Note that connection string should be blank when using Perfion Cloud based media services. Parameter name in Web.Config file: connectionStrings ->add element with a name ”perfionConn” e.g.:  |
StorageServiceUrl | Perfion Storage Service URL. Parameter is optional and used only when media service should serve binaries from the Perfion Cloud by using Storage Service. Note that this parameter will only be used if PerfionDBConnectionString is not defined. Parameter key in Web.Config file: Perfion.StorageServiceUrl |
StorageServiceKey | Perfion Storage Service API Key. Parameter is optional and used only when media service should serve binaries from the Perfion Cloud by using Storage Service. Note that this parameter will only be used if PerfionDBConnectionString is not defined. Parameter key in Web.Config file: Perfion.StorageServiceKey |
WatermarkRange | Image watermark related parameter which defined how the watermark image must be applied. It is an integer number. Values:
The parameter is optional. Parameter key in Web.Config file: Perfion.WatermarkRange |
WatermarkPath | Defines the path to the image that should be used as watermark. Note that the path is relative to the image service (e.g. Image.aspx) file. The parameter is optional. Please note that if WatermarkPath it is not defined or is invalid, watermarks will not be applied to images served by the Image- and UncachedImage service. Parameter key in Web.Config file: Perfion.Watermark |
NoImageImagePath | The path to an image which will be used when there is no image to show, e.g. when image ID used in request is not found. The parameter is optional and if not defined, the image services will use a default image. The path is relative to the image service (e.g. Image.aspx) file. Parameter key in Web.Config file: Perfion.NoImageFoundImage |
HttpCacheability | The parameter allows to control Cache-Control HTTP header for media services response. Values correspond to .NET HttpCacheability supported values:
The parameter is optional. If not define will use “Server” value. For more information refer to Microsoft .NET documentation: HttpCacheability Enum (System.Web) Parameter key in Web.Config file: Perfion.FileHttpCacheability |
ReadTimeoutInMs | The parameter is used with media cache files which are stored locally in the server file system to determine how long the request should wait while trying to read the cache file if it is occupied by other processes (e.g. because other request are handling the file). The parameter is used only with database media services. Optional parameter. The default value is 5000 milliseconds. Parameter key in Web.Config file: Perfion.BinaryCache_ReaderTimeOut |
WriteTimeoutInMs | The parameter is used with media cache files which are stored locally in the server file system to determine how long the request should wait while trying to write (e.g. create/update) the cache file if it is occupied by other processes (e.g. because other request are handling the file). The parameter is used only with database media services. Optional parameter. The default value is 5000 milliseconds. Parameter key in Web.Config file: Perfion.BinaryCache_WriteTimeOut |
MinimumDiskSpaceInMb | The parameter allows to specify the limit of the disk space which is considered as critically low for media service to operate. If server disk space becomes lower than this parameter defines, the media service will show an error about too low disk space. The media services can generate large cache files in local disc and if there is not enough space, the media service will fail. The use of this parameter prevents such failure and allows identifying the real problem earlier before the whole server could stop responding or crash. Optional parameter. The default value is 100 MB. The parameter is used only with database based media services. Parameter key in Web.Config file: Perfion.DiskSpaceLimitInMb |
CacheRecheckDelayInMs | The parameter defines HTTP caching header expiration time. Optional parameter. The default value is 300000 milliseconds (5 minutes). Parameter key in Web.Config file: Perfion.BinaryCache_CachingTime |
CacheRelativePath | The parameter defines the location where media services cache and log files will be located. Optional parameter. The Default value is “Cache”. The parameter is used only with database based media services. Parameter key in Web.Config file: Perfion.CacheStoragePath |
LogLevel | The parameter defines the logging level. Media services if fails will write log data and this parameter determines how detailed this data should be. Values:
Optional parameter. The Default value is “Error”. Note that logging can also be forced by using service request URL parameters. Parameter key in Web.Config file: Perfion.LogLevel |
Figure 1 and Figure 2 show examples of media services configuration using MediaService.Config and Web.Config.
Media Service Types
There can be multiple media services types based on where from the data is retrieved. The configuration and use of all media service types is the same and the difference is only where from the source data will be located and how the cache will be handled. There might be some other nuances when using different types of media services, but they are not essential are usually a result of how the data can be used when sourced from different locations.
Media service type | Description |
Database based | This is the most common media services type which is setup to use a single Perfion database as a source of binary data. The media service will use the local server’s file system to store cached binary data. The database based media services will be enabled if there is Perfion database connection string provided in media services configuration. |
Perfion Cloud based – via Storage Service | This type of media services can be used only if Perfion Cloud Storage feature is in use and there is Perfion Storage Service set up in the Perfion Cloud. If this feature is enabled, then all Perfion binary data can be migrated from Perfion database to the Perfion Cloud storage and media service can be used to retrieve this Cloud based binary data directly without using access to Perfion database. Perfion Cloud Storage feature allows storing binary data in the Perfion Cloud from multiple Perfion databases, so setting up media services for Cloud binaries would allow accessing all of those binaries by using Perfion Storage Service interface. The database based media services will be enabled if Perfion database connection string provided in media services configuration is removed and instead one specifies StorageServiceUrl and StorageServiceKey parameters. The media services will use the Storage Service as a proxy service to access the data stored in Perfion Cloud storage. This type of media services will use caching which will be based on Perfion Cloud storage and cache files will be saved at the same place where the source data is located. |
Perfion Cloud based – special version | This type of media services is practically the same as “Perfion Cloud based – via Storage Service”, but this is a special version which is built into the Storage Service. This type of media services will be only set up by Perfion and available as part of Storage Service infrastructure provided to users who have ordered Perfion Cloud Storage feature. The most significant difference is that this media service will be hosted and administrated by Perfion while the other one can be installed by users. |
How to Use Media Services
Images and/or files are served by using URL to the resource (image/file). The resource is identified using Perfion binary ID and one can also specify various extra parameters. The template for media services request URL is shown below:
Media service request URL formats |
http://<ServiceHostName>/Perfion/<ServiceDesignation1>?id=<BinaryID>[<ServiceParameters>] |
http://<ServiceHostName>/<ServiceDesignation2>/<BinaryID>/<FileName>[?<ServiceParameters>] |
Where:
ServiceHostName is the host name of the server where the media services are installed.
ServiceDesignation1 is the service file name which will be based on which media service was requested.
File.aspx – File service.
Image.aspx – Image service.
ImageW.aspx – Watermarked image service.
ImageUncached.aspx – Uncashed image service.
ServiceDesignation2 is the service name which will be based on which media service was requested.
file – File service.
image – Image service.
wimage – Watermarked image service.
uimage – Uncashed image service.
BinaryID is Perfion binary ID. It is a GUID type identifier.
FileName is a new media file name with extension. Note that this file name is not used for identification and is not related to the actual binary name saved in Perfion. It is a new name of the file which will be associated with this binary. The extension of the file should match the actual content of the file.
ServiceParameters are various other parameters which can be defined to change how the request must be executed. Parameter use will depend on which media service was requested. Parameters are optional. Refer to Media Services URL Parameters.
Example of HTML code which shows how media services can be used when embedding an image in a web page.
<img src="http://ServiceHostName/Perfion/Image.aspx?id=BinaryID" />
<img src="http://ServiceHostName/image/BinaryID/MyImage.jpg" />
Similarly, files can be retrieved with the following HTML code:
<a href="http://ServiceHostName/Perfion/File.aspx?id=BinaryID" />
<a href="http://ServiceHostName/file/BinaryID/MyFile.zip" />
Similarly, files containing other content such as video, ZIP files, etc. can be included on a web page for download or inline rendering via the proper HTML tags such as object for embedding objects etc.
Media Services URL Parameters
Media services can be used with various parameters to change the behavior of the services. There are parameters which are common to all media services and there are also parameters which are only used with specific media services. The parameters are standard HTTP Get URL parameters and are defined using parameter name and value pairs. Multiple parameters can be defined with a single media service request.
Example how to use URL parameters.
Using media service URL parameters |
?id=<BinaryID>&<Parameter1>=<Parameter1Value>&<Parameter2>=<Parameter2Value> … |
Example of a typical image service request using several URL parameters to change image to JPG format to fit the size of 200x200 pixels.
Common Media Service URL Parameters
These parameters will work with all media services.
URL Parameter | Description |
id | The parameter specifies the ID of Perfion binary. The binary can be of file or image type. The binary ID value can be found via a standard API data query as described in the manual Query Reference. The parameter is mandatory for all media service requests. Value: binary data ID (GUID identifier) |
action | Defines requested binary data as attachment. All binary data served by media services are declared as inline content. This means that if the image is requested using internet browser, then that image in most case will be rendered directly in the internet browser’s window. This is a default behavior, but the actual behavior will depend on the application which handles the response. Some binary data content cannot be rendered inline and the application may ask to download the requested binary file to disk. If it is an internet browser, then by adding the action parameter will cause the browser to open a file Save As dialog, allowing the user to save the file to disk. Value: save |
mime | HTTP MIME type of the output stream, e.g. a label used to identify a type of data. Using this parameter one can overwrite the MIME type of data. By default media services will select MIME type based on binary data file extension or from ‘format’ parameter. Value: a valid HTTM MIME type. Some examples of valid HTTP MIME type values: jpg, bin, gif, etc. |
delete | Removes binary data from cache before serving the response. This will lead that the binary data will be retrieved from the source and the new binary cache data will be created (depends on media service type). Value: 1 |
filename | Overwrites the original binary file name with the name provided as parameter value. Value: new file name |
debug | Forces media services to log information about the request. Media services will log failed requests automatically, but one can also force to log a normal request using this parameter. The log data will be located where the binary cache data is located. Value: 1 |
File Service URL Parameters
File service does not have any special URL parameters.
Image services URL parameters
All image services can use the same URL parameters. Image service related parameters allows processing of image type binary data, e.g. to change image size, type, change background color, etc.
URL Parameter | Description |
format | Changes returned image format to defined format. Value: image format, e.g. JPG, PNG, etc. Supported image formats: BMP, GIF, JPG/JPEG, PNG, TIFF/TIF, EPS, PSD, PDF, SVG, WEBP, AVIF |
dpi | Scales the image exactly to the specified resolution. This parameter cannot be combined with the size or fit parameters. For precision, the parameter value can include a decimal separator (use the period character ‘.’). Value: decimal number |
size | Defines the size in pixels (width x height). The pixels must be expressed in whole integer numbers, i.e. no decimal points are allowed. The size can be interpreted in several ways since it is possible to define width and height ratios that are not equivalent to the original image. How the size is interpreted is controlled by the fit parameter. The default behavior is to scale the image to fit within the specified size by keeping the aspect ratio. Value: <width>x<height>, where width and height are integer numbers. |
fit | Controls how to interpret the size parameter behavior. It can only be used together with size parameter. Value:
|
canvascolor | The requested canvas color of the image. It is only usable when image is resized using size parameter together with fit parameter set to aspectratio. The color must be specified as RGB or ARGB color code in hexadecimal format by using 6 (RGB) or 8 (ARGB) char color code. In case of 8 char color code, the first 2 characters represent the alpha channel value. Value: hexadecimal color value, e.g. ccff33. |
backgroundcolor | Adds a color to transparent parts of the image. This only works when the target image format does not support transparency and the source image format has transparency. In such case the source image transparency will be replaced with background color. Value: hexadecimal color value, e.g. ccff33. |
quality | Image compression quality in percent. Supported only for JPG and PNG format images. Value: integer value >0 and <=100. Default value: 90. |
tiffcomp | TIFF compression method. Values: LZW (Lempel-Ziv and Welch compression), ZIP (Deflate compression) or None. Default value is LZW. The parameter can be used only if the target image format is a TIFF image. |
colorprof | The color profile of the target image. It is only usable with images which support color profiles. If specified the image colors will be converted to that color profile and the profile itself will be embedded to the image file. Values: Original (keep the original color profile), CMYK (Coated FOGRA39), sRGB, AdobeRGB1998, ProPhoto. |
usepoi | The request to use the Point-of-Interest (POI) of the image if it has POI specified in its metadata. If image does not have POI specified or the POI is not used, then POI will be equivalent to value 50x50 which is the center of the image. Values: 0 (do not use POI) and 1 (use POI). Default value: 0. The parameter can only be used with size and fit parameters when fit parameter is set to crop or smart. |
poi | The request to use the custom Point-of-Interest (POI) of the image. This parameter can only be used if usepoi is used and set to ‘1’. If this parameter is used, then it will overwrite the original image POI value saved as its metadata. Value is of format <X>x<Y> where X and Y are relative image horizontal and vertical coordinates expressed in %. The reference point is image top right corner which will have value 0x0. The bottom right corner of the image will have value 100x100. The center of the image will have value 50x50. Values for X and Y coordinates must be integer values >=0 and <=100. The parameter can only be used with size and fit parameters when fit parameter is set to crop or smart. |
Image Watermarking
For protection of images, it is possible to automatically place a watermark on all images delivered by the image services. To enable watermarking, watermark image and -range must be defined in the configuration of the media services as described in the Media Service Configuration section.
Watermark Sizing and Appearance
Watermark image is applied by creating a specific watermark image that is used to overlay any of the images delivered by the image services.
The watermark image is always applied in the lower left hand corner. If the watermark image is larger than the image it is applied to, it is scaled down to fit within the image, which means it will then fill out 100% of one of the dimensions. If it is desired to only fill e.g. max. 75% of any dimension, the Watermarking image should be created on an oversized Image canvas with a transparent background, which will then allow full flexibility in how it will appear.
In the same way, the part of the watermark image that should overlay an image can also contain a degree of transparency in order to make the watermark appear smooth and less dominant.
Media Services Functionality Comparison
The table below shows how different media services can handle different type of data.
Service name | File | Image | ImageW | ImageUncached |
File type binaries | Yes | Yes | No | Yes |
File type binaries which have image format | Yes | Yes | No | Yes |
Image type binaries | Yes | Yes | Yes | Yes |
Process image (resize, change format, etc.) – file type binary | No | No | No | No |
Process image (resize, change format, etc.) – image type binary | Yes | Yes | Yes | Yes |
Watermark image | No | Yes | Yes | Yes |
HTTP GET vs. HTTP HEAD Request
A typical media service request is a HTTP GET request which will lead to a typical media service response which includes binary data.
When sending HTTP HEAD request media services will respond with response which only defines the headers without sending the actual content.