@azure/storage-blob

NewRetryPolicyFactory

• NewRetryPolicyFactory(retryOptions?: StorageRetryOptions): RequestPolicyFactory

• A factory method used to generated a RetryPolicy factory.

  export

  Parameters

  • Optional retryOptions: StorageRetryOptions

  Returns RequestPolicyFactory

appendToURLPath

• appendToURLPath(url: string, name: string): string

• Append a string to URL path. Will remove duplicated "/" in front of the string when URL path ends with a "/".

  export

  Parameters

  • url: string

    Source URL string

  • name: string

    String to be appended to URL

  Returns string

  An updated URL string

base64decode

• base64decode(encodedString: string): string

• Base64 decode.

  export

  Parameters

  • encodedString: string

  Returns string

base64encode

• base64encode(content: string): string

• Base64 encode.

  export

  Parameters

  • content: string

  Returns string

blobToArrayBuffer

• blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer>

• Convert a Browser Blob object into ArrayBuffer.

  export

  Parameters

  • blob: Blob

  Returns Promise<ArrayBuffer>

blobToString

• blobToString(blob: Blob): Promise<string>

• Convert a Browser Blob object into string.

  export

  Parameters

  • blob: Blob

  Returns Promise<string>

createSpan

• createSpan(operationName: string, tracingOptions?: OperationTracingOptions): object

• Creates a span using the global tracer.

  Parameters

  • operationName: string

  • Default value tracingOptions: OperationTracingOptions = {}

    The options for the underlying http request.

  Returns object

ensureCpkIfSpecified

• ensureCpkIfSpecified(cpk: CpkInfo | undefined, isHttps: boolean): void

• Parameters

  • cpk: CpkInfo | undefined

  • isHttps: boolean

  Returns void

escapeURLPath

• escapeURLPath(url: string): string

• Reserved URL characters must be properly escaped for Storage services like Blob or File.

  URL encode and escape strategy for JS SDKs

  When customers pass a URL string into XxxClient classes constrcutor, the URL string may already be URL encoded or not. But before sending to Azure Storage server, the URL must be encoded. However, it's hard for a SDK to guess whether the URL string has been encoded or not. We have 2 potential strategies, and chose strategy two for the XxxClient constructors.

  Strategy One: Assume the customer URL string is not encoded, and always encode URL string in SDK.

  This is what legacy V2 SDK does, simple and works for most of the cases.

  • When customer URL string is "http://account.blob.core.windows.net/con/b:", SDK will encode it to "http://account.blob.core.windows.net/con/b%3A" and send to server. A blob named "b:" will be created.
  • When customer URL string is "http://account.blob.core.windows.net/con/b%3A", SDK will encode it to "http://account.blob.core.windows.net/con/b%253A" and send to server. A blob named "b%3A" will be created.

  But this strategy will make it not possible to create a blob with "?" in it's name. Because when customer URL string is "http://account.blob.core.windows.net/con/blob?name", the "?name" will be treated as URL paramter instead of blob name. If customer URL string is "http://account.blob.core.windows.net/con/blob%3Fname", a blob named "blob%3Fname" will be created. V2 SDK doesn't have this issue because it doesn't allow customer pass in a full URL, it accepts a separate blob name and encodeURIComponent for it. We cannot accept a SDK cannot create a blob name with "?". So we implement strategy two:

  Strategy Two: SDK doesn't assume the URL has been encoded or not. It will just escape the special characters.

  This is what V10 Blob Go SDK does. It accepts a URL type in Go, and call url.EscapedPath() to escape the special chars unescaped.

  • When customer URL string is "http://account.blob.core.windows.net/con/b:", SDK will escape ":" like "http://account.blob.core.windows.net/con/b%3A" and send to server. A blob named "b:" will be created.
  • When customer URL string is "http://account.blob.core.windows.net/con/b%3A", There is no special characters, so send "http://account.blob.core.windows.net/con/b%3A" to server. A blob named "b:" will be created.
  • When customer URL string is "http://account.blob.core.windows.net/con/b%253A", There is no special characters, so send "http://account.blob.core.windows.net/con/b%253A" to server. A blob named "b%3A" will be created.

  This strategy gives us flexibility to create with any special characters. But "%" will be treated as a special characters, if the URL string is not encoded, there shouldn't a "%" in the URL string, otherwise the URL is not a valid URL. If customer needs to create a blob with "%" in it's blob name, use "%25" insead of "%". Just like above 3rd sample. And following URL strings are invalid:

  • "http://account.blob.core.windows.net/con/b%"
  • "http://account.blob.core.windows.net/con/b%2"
  • "http://account.blob.core.windows.net/con/b%G"

  Another special character is "?", use "%2F" to represent a blob name with "?" in a URL string.

  Strategy for containerName, blobName or other specific XXXName parameters in methods such as containerClient.getBlobClient(blobName)

  We will apply strategy one, and call encodeURIComponent for these parameters like blobName. Because what customers passes in is a plain name instead of a URL.

  see

  https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata

  see

  https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-shares--directories--files--and-metadata

  export

  Parameters

  • url: string

  Returns string

extractConnectionStringParts

• extractConnectionStringParts(connectionString: string): ConnectionString

• Extracts the parts of an Azure Storage account connection string.

  export

  Parameters

  • connectionString: string

    Connection string.

  Returns ConnectionString

  String key value pairs of the storage account's url and credentials.

generateAccountSASQueryParameters

• generateAccountSASQueryParameters(accountSASSignatureValues: AccountSASSignatureValues, sharedKeyCredential: StorageSharedKeyCredential): SASQueryParameters

• ONLY AVAILABLE IN NODE.JS RUNTIME.

  Generates a SASQueryParameters object which contains all SAS query parameters needed to make an actual REST request.

  see

  https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-an-account-sas

  memberof

  AccountSASSignatureValues

  Parameters

  • accountSASSignatureValues: AccountSASSignatureValues

  • sharedKeyCredential: StorageSharedKeyCredential

  Returns SASQueryParameters

generateBlobSASQueryParameters

• generateBlobSASQueryParameters(blobSASSignatureValues: BlobSASSignatureValues, sharedKeyCredential: StorageSharedKeyCredential): SASQueryParameters
• generateBlobSASQueryParameters(blobSASSignatureValues: BlobSASSignatureValues, userDelegationKey: UserDelegationKey, accountName: string): SASQueryParameters

• ONLY AVAILABLE IN NODE.JS RUNTIME.

  Creates an instance of SASQueryParameters.

  Only accepts required settings needed to create a SAS. For optional settings please set corresponding properties directly, such as permissions, startsOn and identifier.

  WARNING: When identifier is not provided, permissions and expiresOn are required. You MUST assign value to identifier or expiresOn & permissions manually if you initial with this constructor.

  Fill in the required details before running the following snippets.

  example

  // Generate service level SAS for a container
  const containerSAS = generateBlobSASQueryParameters({
      containerName, // Required
      permissions: ContainerSASPermissions.parse("racwdl"), // Required
      startsOn: new Date(), // Required
      expiresOn: new Date(new Date().valueOf() + 86400), // Optional. Date type
      ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional
      protocol: SASProtocol.HttpsAndHttp, // Optional
      version: "2016-05-31" // Optional
    },
    sharedKeyCredential // StorageSharedKeyCredential - `new StorageSharedKeyCredential(account, accountKey)`
  ).toString();

  example

  // Generate service level SAS for a container with identifier
  // startsOn & permissions are optional when identifier is provided
  const identifier = "unique-id";
  await containerClient.setAccessPolicy(undefined, [
    {
      accessPolicy: {
        expiresOn: new Date(new Date().valueOf() + 86400), // Date type
        permissions: ContainerSASPermissions.parse("racwdl").toString(),
        startsOn: new Date() // Date type
      },
      id: identifier
    }
  ]);
  
  const containerSAS = generateBlobSASQueryParameters(
    {
      containerName, // Required
      identifier // Required
    },
    sharedKeyCredential // StorageSharedKeyCredential - `new StorageSharedKeyCredential(account, accountKey)`
  ).toString();

  // Fill in the required details before running the snippet.

  example

  // Generate service level SAS for a blob
  const blobSAS = generateBlobSASQueryParameters({
      containerName, // Required
      blobName, // Required
      permissions: BlobSASPermissions.parse("racwd"), // Required
      startsOn: new Date(), // Required
      expiresOn: new Date(new Date().valueOf() + 86400), // Optional. Date type
      cacheControl: "cache-control-override", // Optional
      contentDisposition: "content-disposition-override", // Optional
      contentEncoding: "content-encoding-override", // Optional
      contentLanguage: "content-language-override", // Optional
      contentType: "content-type-override", // Optional
      ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional
      protocol: SASProtocol.HttpsAndHttp, // Optional
      version: "2016-05-31" // Optional
    },
    sharedKeyCredential // StorageSharedKeyCredential - `new StorageSharedKeyCredential(account, accountKey)`
  ).toString();

  export

  Parameters

  • blobSASSignatureValues: BlobSASSignatureValues

  • sharedKeyCredential: StorageSharedKeyCredential

  Returns SASQueryParameters

• ONLY AVAILABLE IN NODE.JS RUNTIME.

  Creates an instance of SASQueryParameters. WARNING: identifier will be ignored when generating user delegation SAS, permissions and expiresOn are required.

  example

  // Generate user delegation SAS for a container
  const userDelegationKey = await blobServiceClient.getUserDelegationKey(startsOn, expiresOn);
  const containerSAS = generateBlobSASQueryParameters({
      containerName, // Required
      permissions: ContainerSASPermissions.parse("racwdl"), // Required
      startsOn, // Required. Date type
      expiresOn, // Optional. Date type
      ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional
      protocol: SASProtocol.HttpsAndHttp, // Optional
      version: "2018-11-09" // Must >= 2018-11-09 to generate user delegation SAS
    },
    userDelegationKey, // UserDelegationKey
    accountName
  ).toString();

  export

  Parameters

  • blobSASSignatureValues: BlobSASSignatureValues

  • userDelegationKey: UserDelegationKey

    Return value of blobServiceClient.getUserDelegationKey()

  • accountName: string

  Returns SASQueryParameters

generateBlockID

• generateBlockID(blockIDPrefix: string, blockIndex: number): string