Locator
Locator provides an entry point to access the files contained in an Asset. An AccessPolicy is used to define the permissions and duration that a client has access to a given Asset. Locators can have a many to one relationship with an AccessPolicy, such that different Locators can provide different start times and connection types to different clients while all using the same permission and duration settings; however, because of a shared access policy restriction set by Azure storage services, you cannot have more than five unique Locators associated with a given Asset at one time. For more information, see Using a Shared Access Signature (REST API).
Often, you need to transform a Locator Uri in order to access various file formats. For example, the SAS locator’s Path property gives access to the container. To access files, you need to embed the file name between the host and SAS signature. When working with OnDemandOrigin locators, the Path property is not useful until protocol-specific part is added to it.
The following rules govern when a Locator can be created and updated:
Access Signature (SAS) URL Locators used with AccessPolicies that define read permissions, as well as Origin Locators, cannot be created until after the files have been uploaded to an Asset.. SAS URL Locators, which are used to download or upload files, can be created before the files are uploaded only if they are used with AccessPolicies that specify write permissions.
You cannot update a SAS URL Locator after it has been created; however, other Locator types, such as origin locators, can be updated with new StartTime values.
SAS locators' URLs will change every time storage keys of the associated storage account get updated. For more information, see How To: Update Media Services after Rolling Storage Access Keys
There may be a 30-40 second delay after a Locator is created to when it is available for use. This issue applies to both SAS URL and OnDemandOrigin locators.
Note
Locators are not designed for managing per-user access control. To give different access rights to individual users, use Digital Rights Management (DRM) solutions.
This article gives an overview of the Locator entity and also demonstrates how to execute various operations with the Media Services REST API.
Important
When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests.
For more information, see Setup for Media Services REST API Development and Connecting to Media Services with the Media Services REST API.
Locator Entity Properties
| Property | Type | Description |
|---|---|---|
IdOptional. Cannot be updated after the entity has been created. |
Edm.String | Unique identifier set by Media Services. |
NameOptional. |
Edm.String | The name of the locator. Maximum length is 4000. |
ExpirationDateTimeWrite-only. Use a MERGE HTTP request, to update the ExpirationDateTime value. |
Edm.DateTime | The value (represented in milliseconds since midnight Jan 1, 1970) when the locator can no longer be used to access the specified asset. The ExpirationDateTime must be in the following DateTime format: YYYY-MM-DDTHH:mm:ssZ (for example, "2014-05-23T17:53:50Z"). |
TypeRequired. Cannot be updated after the entity has been created. |
Edm.Int32 | Enumeration value that describes the type of Locator. Valid values are: - None = 0: This is the default enumeration value. No valid locator will have this type - SAS = 1: Specifies Shared Access Signature (Sas) locator type - OnDemandOrigin = 2: Specifies a locator type, which refers to an Azure Media Service On-Demand Origin streaming endpoint |
PathRead-only. Set by Media Services. |
Edm.String | URL used for accessing Asset files. |
BaseUriRead-only. Set by Media Services. |
Edm.String | Part of the locator that provides the store/service/container information about the asset. (for example, Dns Host name http://someservice.cloudapp.net) |
ContentAccessComponentRead-only. Set by Media Services. |
Edm.String | Part of the URI needed to access the content. The location of this token in the final media URL depends on the locator type, media type, and streaming service. |
AccessPolicyIdRead-only. Set by Media Services. |
Edm.String | The ID of the AccessPolicy that defines the permissions and duration for the Locator URL. The List permission should not be used when creating OnDemandOrigin locators. |
AssetIdRead-only. Set by Media Services. |
Edm.String | The ID of the Asset that contains the content you want to provide access to. |
StartTimeOptional. |
Edm.DateTime | The date and time when your locator will be available for clients to use. Tip: If you need to upload your files immediately, you should set your StartTime value to five minutes before the current time. This is because there may be clock skew between your client machine and Media Services. Also, your StartTime value must be in the following DateTime format: YYYY-MM-DDTHH:mm:ssZ (for example, "2014-05-23T17:53:50Z"). |
AssetPolicyRead-only. Set by Media Services. |
AssetPolicy entity set |
Navigation property to an AccessPolicy instance. |
AssetRead-only. Set by Media Services. |
Asset entity set |
Navigation property to an Asset instance. |
Create a Locator
Locators can be created with a POST HTTP request.
| Method | Request URI | HTTP Version |
|---|---|---|
| POST | https://<accountname>.restv2.<location>.media.azure.net/api/Locators | HTTP/1.1 |
Note
SAS locators' URLs will change every time storage keys of the associated storage account get updated. For more information, see How To: Update Media Services after Rolling Storage Access Keys
Sample Request
To get the latest x-ms-version:, see Media Services REST.
POST https://<accountname>.restv2.<location>.media.azure.net/api/Locators HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.19
Authorization: Bearer <token value>
Host: media.windows.net
Content-Length: 182
Expect: 100-continue
{"AccessPolicyId": "nb:pid:UUID:25544a8f-8ccf-43b1-a188-2a860b35bffa", "AssetId" : "nb:cid:UUID:d062e5ef-e496-4f21-87e7-17d210628b7c", "StartTime" : "2014-05-17T16:45:53", "Type":1}
For more information, see Delivering Assets with the Media Services REST API.
List Locators
Locators can be retrieved using a GET HTTP request.
| Method | Request URI | HTTP Version |
|---|---|---|
| GET | GET https://<accountname>.restv2.<location>.media.azure.net/api/Locators | HTTP/1.1 |
| Method | Request URI | HTTP Version |
|---|---|---|
| GET | https://<accountname>.restv2.<location>.media.azure.net/api/Locators('locatorid') | HTTP/1.1 |
| Method | Request URI | HTTP Version |
|---|---|---|
| GET | https://<accountname>.restv2.<location>.media.azure.net/api/Assets('assetid')/Locators | HTTP/1.1 |
Sample Request
To get the latest x-ms-version:, see Media Services REST.
GET https://<accountname>.restv2.<location>.media.azure.net/api/Locators('nb:lid:UUID:627cbafb-3d81-4623-97c2-2194282b6d16') HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.19
Authorization: Bearer <token value>
Host: media.windows.net
Update a Locator
Origin Locators can be updated using a MERGE HTTP request.
| Method | Request URI | HTTP Version |
|---|---|---|
| MERGE | https://<accountname>.restv2.<location>.media.azure.net/api/Locators('locatorid') | HTTP/1.1 |
Sample Request
To get the latest x-ms-version:, see Media Services REST.
MERGE https://<accountname>.restv2.<location>.media.azure.net/api/Locators('nb:lid:UUID:5bfcb65d-843d-4d5e-bf71-9306ecb08203') HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.19
Authorization: Bearer <token value>
Host: media.windows.net
Content-Length: 38
Expect: 100-continue
{"StartTime" : "2014-05-17T16:45:53"}
Delete a Locator
Locators can be deleted using a DELETE HTTP request.
| Method | Request URI | HTTP Version |
|---|---|---|
| DELETE | https://<accountname>.restv2.<location>.media.azure.net/api/Locators('locatorid') | HTTP/1.1 |
Sample Request
To get the latest x-ms-version:, see Media Services REST.
DELETE https://<accountname>.restv2.<location>.media.azure.net/api/Locators('nb:lid:UUID:9f0e0cee-8ea5-46c4-b985-5a7cd30e7623') HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.19
Authorization: Bearer <token value>
Host: media.windows.net
Content-Length: 0
Connection: Keep-Alive
See Also
Delivering Assets with the Media Services REST API
ContentKey
Asset
AccessPolicy
AssetFile
JobTemplate
Job
MediaProcessor
Task
TaskTemplate
Quotas and Limitations