How to use

Credentials and Signature

Create a Microsoft account and navigate to Microsoft Azure Portal , then there follow the next guidelines:

Create a storage account - Azure Storage 

After this need to set our SAS (Shared access Signature)

Grant limited access to data with shared access signatures (SAS) - Azure Storage 

This will be the the SIG present in every API.

After setting the Blob Storage ready, the we start building towards the component in OS Service studio

Building the REST API in Service Studio

Since we need to include the signature in the HTTP Request, another API must be called previously to retrieve the security token and Save it in the system, and refresh when out of date. (Not yet done) Currently this should be manual, a Date of expiration could be set to the SAS, so we can do this manually, put in a site property and work with that, a generate is available, but no API ready exists to make this automation. (Further developments could help this, see the road map of the component.)

Azure Blob API returns a XML in all API’s, we need to Convert To JSON , so we can deserialize, for this an example action is present in the module.

After some work the API that are possible are:

Others exists but need configuration and specification in azure account (Future developments could be arranged)

Configuration of the API

So having in mind that the Azure account is created and Shared access Signature(SAS) is created, if not follow the links above, and configure both requirements.

The base URL for the Blob Storage will be:

https://myaccount.blob.core.windows.net , and the my account will be replaced for the storage account name, after this everything will be API related, Also in every URL , Signature will be present, the “Sig” will be filled with SAS Account, this will allowed the authorization to work with the storage account. I Recommend since there is no automation of the SAS, To created a SAS with a long expiry date and put it in site property.

API List and Configuration

List Containers

https://myaccount.blob.core.windows.net/?{Sig}&comp=list

For List Containers, only the sig is need as input, it will return a list of container that exist in the storage, also the properties of each container will be retrieve.

Get Blob Storage Properties

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container

To get only the properties of the container, a container name is required

Get Account Information

https://myaccount.blob.core.windows.net/?{Sig}&restype=account&comp=properties

This API only requires the Sig, it will give the generic account information , like SKU name and specifications

Create Container

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container

API to create a container, the name of the container is needed in URL, the container will be created with this name, remember that spaces and capital letters are not allowed.

Get Container Properties

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container

To retrieve information about a container just substitute the container name for the container we want to get information about.

Get Container Metadata

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container&comp=metadata

Retrieve container metadata information

Get Container ACL

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container&comp=acl

Gets the public access policy and any stored access policies for the container.

Set Container ACL

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container&comp=acl

Sets the public access policy and any stored access policies for the container.

Lease Container

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&comp=lease&restype=container

Establishes and manages a lock on write and delete operations. To delete or write to a locked blob, a client must provide the lease ID. So besides the Sig and Container name, the following will be needed

Lease Action options:

• Acquire, to request a new lease.

• Renew, to renew an existing lease.

• Change, to change the ID of an existing lease.

• Release, to free the lease if it is no longer needed so that another client may immediately acquire a lease against the container.

• Break, to end the lease but ensure that another client cannot acquire a new lease until the current lease period has expired.

Lease Duration options:

• Required for acquire. Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change.

Lease Id

• Optional for acquire, required for change. Proposed lease ID, in a GUID string format. The Blob service returns 400 (Invalid request) if the proposed lease ID is not in the correct format. 

Date

• Required. Specifies the Coordinated Universal Time (UTC) for the request.

Delete Container

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container

Deletes the container and any blobs that it contains.

List Blobs

https://myaccount.blob.core.windows.net/{ContainerName}?{Sig}&restype=container&comp=list

Lists all of the blobs in a container. Required container name and Sig

Put Blob (Upload Blob)

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}

Creates a new blob or replaces an existing blob within a container.

Requires the Container Name, Blob name and Blob Type

If the blob name already exists it will substitute the old one , for blob type use the following options:

• BlockBlob 

  • Most common used in blob storage, it will store a simple file . The other options are more specific, please consult the link of the title for more information.

• PageBlob 

• AppendBlob

Get Blob

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}

API that will return the binary data of the blob file

Get Blob Properties

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}

Besides this equal to the get blob API, it will return plain text (XML) with information about the blob

Set Blob Expiry

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}&comp=expiry

Sets expiry time for an existing blob.

API to set an expiration date to the blob will be required Conatiner name, blob name affected, and Sig, But also:

• Expiry Option

• Expiry Time

Optional. The time when to expire the file. The format for expiry time varies corresponding to the expiry-option.

Get Blob Tags

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}&comp=tags

Retrieve the tags aggregated to the blob.

Set Blob Tags

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}&comp=tags

Set tags to the blob, need to be input as a XML text like this:

<?xml version="1.0" encoding="utf-8"?>
<Tags>
<TagSet>
<Tag>
              <Key>tag-name-1</Key>
              <Value>tag-value-1</Value>
        </Tag>
         <Tag>
              <Key>tag-name-2</Key>
              <Value>tag-value-2</Value>
        </Tag>
     </TagSet>
</Tags>

Find Blobs By Tags

https://myaccount.blob.core.windows.net/?{Sig}&comp=blobs&where={SearchValue}

Search the blob using the tags, if they exist in blob, put your input on the search value, the rules to construct the search value are:

Delete Blob

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}

Marks Blob for delete

Undelete Blob

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?comp=undelete&{Sig}

Retrieves the blob marked for delete and make live again

Snapshot Blob

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}&comp=snapshot

Creates a read-only snapshot of a blob.

Copy Blob

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}

Copies a source blob to a destination blob in this storage account or in another storage account.

Need to input the source of the copy:

“Here are some examples of source object URLs:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>

When the source object is a file in Azure Files, the source URL uses the following format. Note that the URL must include a valid SAS token for the file.

- https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sastoken

In versions before 2012-02-12, blobs can be copied only within the same account, and a source name can use these formats:

- Blob in named container: /accountName/containerName/blobName
- Snapshot in named container: /accountName/containerName/blobName?snapshot=<DateTime>
- Blob in root container: /accountName/blobName
- Snapshot in root container: /accountName/blobName?snapshot=<DateTime>"

Put Block (Add_BlobPart)

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}&comp=block&blockid={BlockId}

Creates a new block to be committed as part of a block blob.

About block Id:

Required. A valid Base64 string value that identifies the block. Prior to encoding, the string must be less than or equal to 64 bytes in size.

For a given blob, the length of the value specified for the blockid parameter must be the same size for each block.

Note that the Base64 string must be URL-encoded.

Put Block From URL

https://myaccount.blob.core.windows.net/{ContainerName}/{BlobName}?{Sig}&comp=block&blockid={BlockId}

Creates a new block to be committed as part of a block blob where the contents are read from a URL.

About block Id:

Required. A valid Base64 string value that identifies the block. Prior to encoding, the string must be less than or equal to 64 bytes in size.

For a given blob, the length of the value specified for the blockid parameter must be the same size for each block.

Note that the Base64 string must be URL-encoded.

Also Source

Required. Specifies the URL of the source blob. The value may be a URL of up to 2 KiB in length that specifies a blob. The value should be URL-encoded as it would appear in a request URI. The source blob must either be public or must be authorized via a shared access signature. If the source blob is public, no authorization is required to perform the operation. Here are some examples of source object URLs:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>

Road Map:

Some Work still need to be made, but this will involve a lot of more research, and maybe building things that still doesn't  exist in Microsoft, I will leave it the Road Map below:

• Make the authentication more autonomous, there is a way of generate the SAS without having to input it in a site property , but only the generate, and not the retrieval , No API created (as far as my research went) to do both cases (Generate and Retrieve) Generate SAS token 

• There is 3 types of authentication, currently the component uses the SAS one, the idea its to make it ready for any of the other missing: 

  • Shared Key

  • Azure Active Directory (Azure AD)

• Still missing some of the API, regarding some special configurations in Azure Blob Storage, most of them regarding Page Blob and Append Blob