# Azure Blob Storage

{% hint style="info" %}
The following documentation is for **Azure Blob Storage v1.3.4** *(BDK)*.
{% endhint %}

## Overview

Azure Blob Storage provides massively scalable object storage for unstructured data in the cloud. This integration enables automated file management, data archiving, and cloud storage workflows within Microsoft Azure. Leverage enterprise-grade cloud storage for secure and scalable data operations.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Azure Blob Storage**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Azure account name and Azure account Key

Connect to a Blob Storage account using the provided account key.

| Label              | Description            | Type        |
| ------------------ | ---------------------- | ----------- |
| Azure account name | The Azure account name | `text`      |
| Azure account Key  | The Azure account Key  | `sensitive` |

### Connect using Azure Account Name, SAS Token and Container Name

Connect to an API using the provided API key.

| Label              | Description            | Type        |
| ------------------ | ---------------------- | ----------- |
| Azure Account Name | The Azure account name | `text`      |
| SAS Token          | The SAS token          | `sensitive` |
| Container Name     | The container name     | `text`      |

## Procedures

### to copy an item to a folder

Copy an item to a folder

**Input Concepts**

| Concept                             | Description                                                                                                        | Type                                               | Required | Default Value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | -------- | ------------- |
| `item`                              | The item (file or folder) to copy                                                                                  | `azure file reference` or `azure folder reference` | Yes      | (no default)  |
| [`folder`](#azure-folder-reference) | The folder to copy the item to                                                                                     | `azure folder reference`                           | Yes      | (no default)  |
| `conflict behavior`                 | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text`                                             | No       | fail          |
| `updated name`                      | The new name to replace with                                                                                       | `text`                                             | No       | (no default)  |

**Examples**

Copy an item (file/folder) to another folder in Azure Blob Storage

```generic
get a folder at "container_name/google/"
use the above as the folder
get the folder's item whose path prefix is "logs.txt"
use the above as the item
get a folder at "container_name/apple/"
use the above as the second folder
copy the item to the second folder
```

### to create a (folder) in another folder

Create a (folder) in another folder

**Input Concepts**

| Concept                                     | Description                                                                                                        | Type                     | Required | Default Value |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------ | -------- | ------------- |
| [`another folder`](#azure-folder-reference) | The folder to create the (folder) in                                                                               | `azure folder reference` | Yes      | (no default)  |
| `folder name`                               | The name of the (folder) to create                                                                                 | `text`                   | Yes      | (no default)  |
| `conflict behavior`                         | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text`                   | No       | fail          |

**Output Concepts**

| Concept                             | Description                       | Type                     |
| ----------------------------------- | --------------------------------- | ------------------------ |
| [`folder`](#azure-folder-reference) | a reference to the created folder | `azure folder reference` |

**Examples**

Create a folder in another folder in Azure Blob Storage

```generic
get a folder at "container_name/google"
use the above as the another folder
the name is "banana/"
create a folder in the another folder with
    the folder name is the name
```

### to delete an item

Delete an item (file or folder)

**Input Concepts**

| Concept | Description                         | Type                                               | Required | Default Value |
| ------- | ----------------------------------- | -------------------------------------------------- | -------- | ------------- |
| `item`  | The item (file or folder) to delete | `azure file reference` or `azure folder reference` | Yes      | (no default)  |

**Examples**

Delete an item (file/folder) from Azure Blob Storage

```generic
create a json
use the above as the file
set the file's container_name to "container_name"
set the file's blob_name to "google/test.txt"
delete an item with
    the item is the file
```

### to download a file

Download a file

**Input Concepts**

| Concept                         | Description                                | Type                   | Required | Default Value |
| ------------------------------- | ------------------------------------------ | ---------------------- | -------- | ------------- |
| [`file`](#azure-file-reference) | The file reference to the file to download | `azure file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description              | Type   |
| -------- | ------------------------ | ------ |
| `answer` | the file as an IO object | `file` |

**Examples**

Download an item from Azure Blob storage

```generic
get a folder at "container/apple/"
get the folder's item whose path prefix is "test.txt"
use the above as the file
download the file
```

### to get a (folder) at a path

Get a reference to a folder.

**Input Concepts**

| Concept | Description            | Type   | Required | Default Value |
| ------- | ---------------------- | ------ | -------- | ------------- |
| `path`  | The path to the folder | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept                             | Description        | Type                     |
| ----------------------------------- | ------------------ | ------------------------ |
| [`folder`](#azure-folder-reference) | a folder reference | `azure folder reference` |

**Examples**

Retrieve the folder at a path

```generic
get a folder at "container/apple/"
```

### to get a (root folder) from a container

Get a reference to the root folder.

**Input Concepts**

| Concept     | Description            | Type   | Required | Default Value |
| ----------- | ---------------------- | ------ | -------- | ------------- |
| `container` | The path to the folder | `text` | No       | (no default)  |

**Output Concepts**

| Concept                                  | Description        | Type                     |
| ---------------------------------------- | ------------------ | ------------------------ |
| [`root folder`](#azure-folder-reference) | a folder reference | `azure folder reference` |

**Examples**

Retrieve the root folder of the Azure Container

```generic
the container is "abc_container"
get a root folder from the container
```

### to get some (folder's items)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get items from a folder.

**Input Concepts**

| Concept                             | Description                                       | Type                     | Required | Default Value |
| ----------------------------------- | ------------------------------------------------- | ------------------------ | -------- | ------------- |
| [`folder`](#azure-folder-reference) | The folder reference from which to list the items | `azure folder reference` | Yes      | (no default)  |

**Output Concepts**

| Concept          | Description                                                         | Type                                               |
| ---------------- | ------------------------------------------------------------------- | -------------------------------------------------- |
| `folder's items` | a list of Items (file or folder) containing the items in the folder | `azure file reference` or `azure folder reference` |

**Examples**

Get the list of the folder items from Azure Blob Storage

```generic
get a folder at "container_name/google/"
use the above as the folder
get the folder's items
```

Get a filtered list of the folder items from Azure Blob Storage

```generic
get a folder at "container_name/google/"
use the above as the folder
get the folder's items whose path prefix is "log_"
```

### to move an item to a folder

Move an item to a folder

**Input Concepts**

| Concept                             | Description                                                                                                        | Type                                               | Required | Default Value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | -------- | ------------- |
| `item`                              | The item (file or folder) to move                                                                                  | `azure file reference` or `azure folder reference` | Yes      | (no default)  |
| [`folder`](#azure-folder-reference) | The folder to move the item to                                                                                     | `azure folder reference`                           | Yes      | (no default)  |
| `conflict behavior`                 | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text`                                             | No       | fail          |

**Examples**

Move an item (file/folder) to another folder in AWS S3

```generic
create a json
use the above as the item
set the item's container_name to "container_name"
set the item's blob_name to "kognitos-data.txt"
get a folder at "container_name/google"
use the above as the folder
move an item to folder with
    the item is the item
    the folder is the folder
```

### to rename an item to a name

Rename an item (file or folder) to a given name

**Input Concepts**

| Concept             | Description                                                                                                        | Type                                               | Required | Default Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | -------- | ------------- |
| `item`              | The item (file or folder) to rename                                                                                | `azure file reference` or `azure folder reference` | Yes      | (no default)  |
| `name`              | The new name of the item                                                                                           | `text`                                             | Yes      | (no default)  |
| `conflict behavior` | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text`                                             | No       | fail          |

**Examples**

Rename an item (file/folder) in Azure Blob Storage

```generic
create a json
use the above as the file
set the file's container_name to "container_name"
set the file's blob_name to "test.txt"
rename item to "test1.txt" with
    the item is the file
```

### to sign a (blob)

Sign a blob

**Input Concepts**

| Concept        | Description                                                              | Type                                               | Required | Default Value |
| -------------- | ------------------------------------------------------------------------ | -------------------------------------------------- | -------- | ------------- |
| `item`         | The item (file or folder) to sign                                        | `azure file reference` or `azure folder reference` | Yes      | (no default)  |
| `expiry hours` | The number of hours the signature should be valid for. Default is 1 hour | `number`                                           | No       | 1             |

**Output Concepts**

| Concept | Description                      | Type                                               |
| ------- | -------------------------------- | -------------------------------------------------- |
| `blob`  | the item signed with the SAS URL | `azure file reference` or `azure folder reference` |

**Examples**

Sign a blob in Azure Blob Storage

```generic
get a folder at "container_name/google"
use the above as the item
sign a blob with
    the item is the item
```

### to upload a (file) to a folder

Upload a file to a folder

**Input Concepts**

| Concept                             | Description                                                                                                        | Type                     | Required | Default Value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------ | -------- | ------------- |
| `file`                              | The file to upload                                                                                                 | `file`                   | Yes      | (no default)  |
| [`folder`](#azure-folder-reference) | The folder to upload the file to                                                                                   | `azure folder reference` | Yes      | (no default)  |
| `file name`                         | The name of the file to upload                                                                                     | `text`                   | Yes      | (no default)  |
| `conflict behavior`                 | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text`                   | No       | fail          |

**Output Concepts**

| Concept                         | Description                        | Type                   |
| ------------------------------- | ---------------------------------- | ---------------------- |
| [`file`](#azure-file-reference) | the reference to the uploaded file | `azure file reference` |

**Examples**

Upload a file to folder in Azure Blob Storage

```generic
the file
get a folder at "container_name/google"
the name is "new_test.txt"
upload the file to the folder with
    the file name is the name
```

## Concepts

### Azure file reference

Represents a reference to a file in an Azure Storage.

| Field Name       | Description                                                                            | Type             |
| ---------------- | -------------------------------------------------------------------------------------- | ---------------- |
| `container_name` | The name of the container.                                                             | `text`           |
| `blob_name`      | The full path of the file within the container, including the file name and extension. | `text`           |
| `account_name`   | The name of the account.                                                               | `optional[text]` |
| `etag`           | Entity tag.                                                                            | `optional[text]` |
| `sas_token`      | SAS token.                                                                             | `optional[text]` |

### Azure folder reference

Represents a reference to a folder in an Azure Storage

| Field Name       | Description                                                                                                    | Type             |
| ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------- |
| `container_name` | The name of the container.                                                                                     | `text`           |
| `path`           | The path of the folder within the container. Should end with a trailing slash ('/') to indicate it's a folder. | `text`           |
| `account_name`   | The name of the account.                                                                                       | `optional[text]` |
| `etag`           | Entity tag                                                                                                     | `optional[text]` |
| `sas_token`      | SAS token.                                                                                                     | `optional[text]` |