This topic has not yet been rated - Rate this topic

Locators

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 Windows 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 Origin Locators, the Path property is not useful until protocol specific part is added to it.

Note
CDN is not a Locator. It is a string manipulation on top of a SAS or OnDemandOrigin locator Path.

The following rules govern when a Locator can be created and updated:

Shared Access Signature (SAS) URL Locators, which are used to download or upload files, can be created before an Asset is published only if they are used with AccessPolicies that specify write permissions. SAS URL Locators used with AccessPolicies that define read permissions, as well as Origin Locators, cannot be created until after an Asset is published.
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.
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.

Important
When accessing entities in Windows Azure 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.

Locator Entity Properties
Create a Locator
List Locators
Update a Locator
Delete a Locator

Important
After successfully connecting to https://media.windows.net, you will receive a 301 redirect specifying another Media Services URI. You must make subsequent calls to the new URI.

Locator Entity Properties

Property

Type

Description

Edm.String

Unique identifier set by Media Services.

ExpirationDateTime

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.

Type

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

Edm.String

URL used for accessing Asset files.

BaseUri

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

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

Edm.String

The Id of the AccessPolicy that defines the permissions and duration for the Locator URL.

AssetId

Edm.String

The Id of the Asset that contains the content you want to provide access to.

StartTime

Edm.DateTime

The date and time when your locator will be available for clients to use.

Tip
If you need clients to access 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 the client and the server. Also, your StartTime value must following the en-US DateTime format month/day/yearhour:minute:second AM/PM.

Create a Locator

Locators can be created with a POST HTTP request.

Method	Request URI	HTTP Version
POST	https://media.windows.net/API/Locators	HTTP/1.1

Sample Request

POST https://media.windows.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.1
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337212980&Issuer=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&HMACSHA256=kK7PbPM3lTAEJYIx5OTWeaSY7zvia358UjPiuvSFHz0%3d
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" : "5/16/2012 1:57:53 PM", "Type":1}

List Locators

Locators can be retrieved using a GET HTTP request.

Method	Request URI	HTTP Version
GET	GET https://media.windows.net/API/Locators	HTTP/1.1

Method	Request URI	HTTP Version
GET	https://media.windows.net/API/Locators('locatorid')	HTTP/1.1

Method	Request URI	HTTP Version
GET	https://media.windows.net/API/Assets('assetid')/Locators	HTTP/1.1

Sample Request

GET https://media.windows.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.1
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337219077&Issuer=https%3a%2f%2fnimbustestaccounts.accesscontrol.windows.net%2f&HMACSHA256=JSeCQMLMDLIm%2fFD%2b8qJL52dShVNGdwg1aqB%2b3GLlq5I%3d
Host: media.windows.net

Update a Locator

Origin and Windows Azure CDN Locators can be updated using a MERGE HTTP request.

Method	Request URI	HTTP Version
MERGE	https://media.windows.net/API/Locators('locatorid')	HTTP/1.1

Sample Request

MERGE https://media.windows.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.1
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337219313&Issuer=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&HMACSHA256=iULfw27Jo4TIBljQr8MDMDh2TX6YZBShgvY9yblaqKU%3d
Host: media.windows.net
Content-Length: 38
Expect: 100-continue

{"StartTime" : "5/16/2012 8:49:05 AM"}

Delete a Locator

Locators can be deleted using a DELETE HTTP request.

Method	Request URI	HTTP Version
DELETE	https://media.windows.net/API/Locators('locatorid')	HTTP/1.1

Sample Request

DELETE https://media.windows.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.1
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337219313&Issuer=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&HMACSHA256=iULfw27Jo4TIBljQr8MDMDh2TX6YZBShgvY9yblaqKU%3d
Host: media.windows.net
Content-Length: 0
Connection: Keep-Alive

Community Additions

ADD

Locators

Locator Entity Properties

Create a Locator

Sample Request

List Locators

Sample Request

Update a Locator

Sample Request

Delete a Locator

Sample Request

See Also

Concepts

Other Resources

Community Additions