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:

  1. 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.

  2. 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.

  3. 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

  4. 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
Id

Optional. Cannot be updated after the entity has been created.
Edm.String Unique identifier set by Media Services.
Name

Optional.
Edm.String The name of the locator. Maximum length is 4000.
ExpirationDateTime

Write-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").
Type

Required. 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
Path

Read-only. Set by Media Services.
Edm.String URL used for accessing Asset files.
BaseUri

Read-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)
ContentAccessComponent

Read-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.
AccessPolicyId

Read-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.
AssetId

Read-only. Set by Media Services.
Edm.String The ID of the Asset that contains the content you want to provide access to.
StartTime

Optional.
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").
AssetPolicy

Read-only. Set by Media Services.
AssetPolicy entity set Navigation property to an AccessPolicy instance.
Asset

Read-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