Azure Blob Storage

The Azure Blob Storage destination writes data to Microsoft Azure Blob Storage. You can use the Azure Blob Storage destination in standalone and cluster batch pipelines. For information about supported versions, see Supported Systems and Versions in the Data Collector documentation.

When you configure the Azure Blob Storage destination, you specify connection information for Azure Blob Storage, including the storage container or file system and authentication method. You can also use a connection to configure the destination.

You specify the blob type to write data to along with a prefix and optional suffix for blob names. For page blobs, you specify the blob and page size, and can configure a start offset to determine where in a page the destination starts writing data.

The destination can generate events for an event stream. For more information about the event framework, see Dataflow Triggers Overview.

Before you use the destination, you must perform a prerequisite task.

Prerequisite

Before configuring the Azure Blob Storage destination, you must ensure that the destination can write the needed objects. The destination uses an authentication method to establish its identity with Azure.

Azure authorizes an identity to read and write objects. Azure provides various authorization methods for specific types of objects. The methods offer different levels of security. You must choose compatible authentication and authorization methods for your objects. Consult the Microsoft Azure Blob Storage documentation for information about the authorization methods.

You must complete appropriate steps for the chosen method, such as configuring an Azure Active Directory application, creating a shared key, or creating a shared access signature (SAS) token.

The Azure Blob Storage destination can use one of the following authentication methods:

OAuth with Service Principal

Connections made with OAuth with Service Principal authentication require the following information:

Application ID - Application ID for the Azure Active Directory Data Collector application. Also known as the client ID.
For information on accessing the application ID from the Azure portal, see the Azure documentation.
Tenant ID - Tenant ID for the Azure Active Directory Data Collector application. Also known as the directory ID.
For information on accessing the tenant ID from the Azure portal, see the Azure documentation.
Application Key - Authentication key or client secret for the Azure Active Directory application. Also known as the client secret.
For information on accessing the application key from the Azure portal, see the Azure documentation.

Azure Managed Identity

Connections made with Azure Managed Identity authentication require the following information:

Application ID - Application ID for the Azure Active Directory Data Collector application. Also known as the client ID.
For information on accessing the application ID from the Azure portal, see the Azure documentation.

Shared Key

Connections made with Shared Key authentication require the following information:

Account Shared Key - Shared access key that Azure generated for the storage account.
For more information on accessing the shared access key from the Azure portal, see the Azure documentation.

SAS Token

Connections made with SAS Token authentication require the following information:

Azure SAS Token - Shared access signature (SAS) token that provides secure access to the needed resources in Azure Blob Storage.
For more information on SAS tokens for storage containers, see the Azure documentation.

Blob Types

The Azure Blob Storage destination can write batches to Azure Blob Storage using one of the following blob types:

Append: The destination creates a single blob for all batches from a thread.; The blob name contains the prefix configured in the destination, the runner ID, and an optional suffix. For example, an append blob with the name test-001.json would be a blob written with the prefix test-, the runner ID 001, and the suffix .json.
Block: The destination creates a blob for each thread and batch.; Like append blobs, block blob names contain the prefix configured in the destination, the runner ID, and an optional suffix. Additionally, block blob names contain an incremental batch counter. For example, a block blob with the name test-0000001-001.json would be a blob written with the prefix test-, the incremental batch counter 0000001, and the runner ID 001, and the suffix .json.
Page: The destination appends a page of the configured page size for every batch containing processed records of the specified data format.; Like append blobs, page blob names contain the prefix configured in the destination, the runner ID, and an optional suffix. For example, a page blob with the name test-001.json would be a blob written with the prefix test-, the runner ID 001, and the suffix .json.

For more information about Azure blob types, see the Azure documentation.

Event Generation

The Azure Blob Storage destination can generate events that you can use in an event stream. When you enable event generation, the Azure Blob Storage destination generates event records each time the destination completes writing to a blob.

The events can be used in any logical way. For example:

With the Email executor to send a custom email after receiving an event.
For an example, see Sending Email During Pipeline Processing.
With a destination to store event information.
For an example, see Preserving an Audit Trail of Events.

For more information about dataflow triggers and the event framework, see Dataflow Triggers Overview.

Event Records

The Azure Blob Storage destination event records include the following event-related record header attributes. Record header attributes are stored as String values.


Record Header Attribute	Description
sdc.event.type	Event type. Uses the following type: Azure Blob Written - Generated when the destination completes writing to a blob.
sdc.event.version	Integer that indicates the version of the event record type.
sdc.event.creation_timestamp	Epoch timestamp when the stage created the event.

The destination can generate the following types of event records:

Azure blob written

The destination generates a file closure event record when it completes writing to a blob.

Azure blob written event records have the sdc.event.type record header attribute set to Azure Blob Written and include the following fields:


Field	Description
container	Name of the container that contains the blob.
blobName	Name of the blob.
recordCount	Number of records written to the blob.

Data Formats

The Azure Blob Storage destination writes data to Azure Blob Storage based on the data format that you select. You can use the following data formats:

Avro

The destination writes records based on the Avro schema. You can use one of the following methods to specify the location of the Avro schema definition:

In Pipeline Configuration - Use the schema that you provide in the stage configuration.
In Record Header - Use the schema included in the avroSchema record header attribute.
Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry. Confluent Schema Registry is a distributed storage layer for Avro schemas. You can configure the destination to look up the schema in Confluent Schema Registry by the schema ID or subject.
If using the Avro schema in the stage or in the record header attribute, you can optionally configure the destination to register the Avro schema with Confluent Schema Registry.

The destination includes the schema definition in each file.

You can compress data with an Avro-supported compression codec. When using Avro compression, avoid using other compression properties in the destination.

Binary

The stage writes binary data to a single field in the record.

Delimited

The destination writes records as delimited data. When you use this data format, the root field must be list or list-map.

You can use the following delimited format types:

Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
MS Excel CSV - Microsoft Excel comma-separated file.
MySQL CSV - MySQL comma-separated file.
Tab-Separated Values - File that includes tab-separated values.
PostgreSQL CSV - PostgreSQL comma-separated file.
PostgreSQL Text - PostgreSQL text file.
Custom - File that uses user-defined delimiter, escape, and quote characters.
Multi Character Delimited - File that uses multiple user-defined characters to delimit fields and lines, and single user-defined escape and quote characters.

JSON

The destination writes records as JSON data. You can use one of the following formats:

Array - Each file includes a single array. In the array, each element is a JSON representation of each record.
Multiple objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.

Parquet

The destination writes a Parquet file for each partition and includes the Parquet schema in every file.

For more information about the Parquet data format, see Parquet Data Format.

Protobuf

Writes a batch of messages in each file.

Uses the user-defined message type and the definition of the message type in the descriptor file to generate the messages in the file.

For information about generating the descriptor file, see Protobuf Data Format Prerequisites.

SDC Record

The destination writes records in the SDC Record data format.

Text

The destination writes data from a single text field to the destination system. When you configure the stage, you select the field to use.

You can configure the characters to use as record separators. By default, the destination uses a UNIX-style line ending (\n) to separate records.

When a record does not contain the selected text field, the destination can report the missing field as an error or to ignore the missing field. By default, the destination reports an error.

When configured to ignore a missing text field, the destination can discard the record or write the record separator characters to create an empty line for the record. By default, the destination discards the record.

Whole File

Streams whole files to the destination system. The destination writes the data to the file and location defined in the stage. If a file of the same name already exists, you can configure the destination to overwrite the existing file or send the current file to error.

By default, written files use the default access permissions for the destination system. You can specify an expression that defines access permissions.

For more information about the whole file data format, see Whole File Data Format.

XML

The destination creates a valid XML document for each record. The destination requires the record to have a single root field that contains the rest of the record data. For details and suggestions for how to accomplish this, see Record Structure Requirement.

The destination can include indentation to produce human-readable documents. It can also validate that the generated XML conforms to the specified schema definition. Records with invalid schemas are handled based on the error handling configured for the destination.

Configuring an Azure Blob Storage Destination

Configure an Azure Blob Storage destination to write data to Microsoft Azure Blob Storage. Before you use the destination, you must perform a prerequisite task.

In the Properties panel, on the General tab, configure the following properties:


General Property	Description
Name	Stage name.
Description	Optional description.
Produce Events	Generates event records when events occur. Use for event handling.
Required Fields	Fields that must include data for the record to be passed into the stage. Tip: You might include fields that the stage uses. Records that do not include all required fields are processed based on the error handling configured for the pipeline.
Preconditions	Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions. Records that do not meet all preconditions are processed based on the error handling configured for the stage.
On Record Error	Error record handling for the stage: Discard - Discards the record. Send to Error - Sends the record to the pipeline for error handling. Stop Pipeline - Stops the pipeline.

On the Azure tab, configure the following properties:


Azure Property	Description
Connection	Connection that defines the information required to connect to an external system. To connect to an external system, you can select a connection that contains the details, or you can directly enter the details in the pipeline. When you select a connection, Control Hub hides other properties so that you cannot directly enter connection details in the pipeline.
Account FQDN	The host name of the Blob Storage account. For example: `<storage account name>.blob.core.windows.net`
Storage Container / File System	Name of the storage container or file system to write to.
Authentication Method	Authentication method used to connect to Azure: OAuth with Service Principal Azure Managed Identity Shared Key SAS Token
Application ID	Application ID for the Azure Active Directory Data Collector application. Also known as the client ID. For information on accessing the application ID from the Azure portal, see the Azure documentation. Available when using the OAuth with Service Principal or the Azure Managed Identity authentication method.
Endpoint Type	Method to provide endpoint details. Available when using the OAuth with Service Principal authentication method.
Tenant ID	Tenant ID for the Azure Active Directory Data Collector application. Also known as the directory ID. For information on accessing the tenant ID from the Azure portal, see the Azure documentation. Available when Endpoint Type is set to Tenant ID.
Endpoint URL	Endpoint URL for the Azure Active Directory Data Collector application. Default is `https://login.microsoftonline.com/<tenant-id>/oauth2/token`. In the URL, specify the tenant ID for the Azure Active Directory Data Collector application. For information on accessing the tenant ID from the Azure portal, see the Azure documentation. Available when Endpoint Type is set to Endpoint URL.
Application Key	Authentication key or client secret for the Azure Active Directory application. Also known as the client secret. For information on accessing the application key from the Azure portal, see the Azure documentation. Available when using the OAuth with Service Principal authentication method.
Account Shared Key	Shared access key that Azure generated for the storage account. For more information on accessing the shared access key from the Azure portal, see the Azure documentation. Available when using the Shared Key authentication method.
Azure SAS Token	Shared access signature (SAS) token that provides secure access to the needed resources in Azure Blob Storage. For more information on SAS tokens for storage containers, see the Azure documentation. Available when using the SAS Token authentication method.
Use Custom Blob Service URL	Enables using a custom Azure Blob Storage URL.
Custom Blob Service URL	Custom Azure Blob Storage URL. Typically uses the following format: `https://<Azure Account>.blob.core.windows.net`

On the Output Files tab, configure the following properties:


Output Files Property	Description
Blob Type	Blob type for the destination to write: Block Append Page
Overwrite	Overwrites the existing blob if it already exists. For block blobs, when this property is disabled, the destination raises an error if the blob exists.
Blob Prefix	Prefix to include in the blob name. Default is `sdc-`.
Blob Suffix	Optional suffix to include in the blob name.
Blob Size	Size of the blob in bytes. The number of bytes must be a multiple of 512. This value is used if overwrite is enabled or the blob does not exist. Required for page blobs.
Page Size	Size of the page in bytes. The number of bytes must be a multiple of 512. Required for page blobs.
Start Offset	Bytes skipped on each page before starting the write. The number of bytes must be a multiple of 512. Available for page blobs.

On the Data Format tab, configure the following property:


Data Format Property	Description
Data Format	Format of data to be written. Use one of the following options: Avro Binary Delimited JSON Parquet Protobuf SDC Record Text Whole File XML

For Avro data, on the Data Format tab, configure the following properties:


Avro Property	Description
Avro Schema Location	Location of the Avro schema definition to use when writing data: In Pipeline Configuration - Use the schema that you provide in the stage configuration. In Record Header - Use the schema in the avroSchema record header attribute. Use only when the avroSchema attribute is defined for all records. Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry.
Avro Schema	Avro schema definition used to write the data. You can optionally use the `runtime:loadResource` function to load a schema definition stored in a runtime resource file.
Register Schema	Registers a new Avro schema with Confluent Schema Registry.
Schema Registry URLs	Confluent Schema Registry URLs used to look up the schema or to register a new schema. To add a URL, click Add and then enter the URL in the following format: `http://<host name>:<port number>`
Basic Auth User Info	User information needed to connect to Confluent Schema Registry when using basic authentication. Enter the key and secret from the `schema.registry.basic.auth.user.info` setting in Schema Registry using the following format: `<key>:<secret>` Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation.
Look Up Schema By	Method used to look up the schema in Confluent Schema Registry: Subject - Look up the specified Avro schema subject. Schema ID - Look up the specified Avro schema ID.
Schema Subject	Avro schema subject to look up or to register in Confluent Schema Registry. If the specified subject to look up has multiple schema versions, the destination uses the latest schema version for that subject. To use an older version, find the corresponding schema ID, and then set the Look Up Schema By property to Schema ID.
Schema ID	Avro schema ID to look up in Confluent Schema Registry.
Include Schema	Includes the schema in each file. Note: Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.
Avro Compression Codec	The Avro compression type to use. When using Avro compression, do not enable other compression available in the destination.

For binary data, on the Data Format tab, configure the following property:


Binary Property	Description
Binary Field Path	Field that contains the binary data.

For delimited data, on the Data Format tab, configure the following properties:


Delimited Property	Description
Delimiter Format	Format for delimited data: Default CSV - File that includes comma-separated values. Ignores empty lines in the file. RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines. MS Excel CSV - Microsoft Excel comma-separated file. MySQL CSV - MySQL comma-separated file. Tab-Separated Values - File that includes tab-separated values. PostgreSQL CSV - PostgreSQL comma-separated file. PostgreSQL Text - PostgreSQL text file. Custom - File that uses user-defined delimiter, escape, and quote characters.
Header Line	Indicates whether to create a header line.
Delimiter Character	Delimiter character for a custom delimiter format. Select one of the available options or use Other to enter a custom character. You can enter a Unicode control character using the format \uNNNN, where N is a hexadecimal digit from the numbers 0-9 or the letters A-F. For example, enter \u0000 to use the null character as the delimiter or \u2028 to use a line separator as the delimiter. Default is the pipe character ( \| ).
Record Separator String	Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use `\r\n` to separate records. Available when using a custom delimiter format.
Escape Character	Escape character for a custom delimiter format. Select one of the available options or use Other to enter a custom character. Default is the backslash character ( \ ).
Quote Character	Quote character for a custom delimiter format. Select one of the available options or use Other to enter a custom character. Default is the quotation mark character ( " ).
Replace New Line Characters	Replaces new line characters with the configured string. Recommended when writing data as a single line of text.
New Line Character Replacement	String to replace each new line character. For example, enter a space to replace each new line character with a space. Leave empty to remove the new line characters.
Charset	Character set to use when writing data.

For JSON data, on the Data Format tab, configure the following properties:


JSON Property	Description
JSON Content	Method to write JSON data: JSON Array of Objects - Each file includes a single array. In the array, each element is a JSON representation of each record. Multiple JSON Objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
Charset	Character set to use when writing data.

For Parquet data, on the Data Format tab, configure the following properties:


Parquet Property	Description
Parquet Schema Location	Location to load the Parquet schema from: Parquet Schema in Record Header - Uses the schema in the `parquetSchema` record header attribute. In Pipeline Configuration - Uses the schema you provide in the stage configuration. Infer from records - The destination infers the schema from the first record of the first batch of data.
Nullable Fields	Allow null values in schema fields. Default is enabled.
Parquet Compression Codec	Compression type for output files: Uncompressed GZIP LZO Snappy
Parquet Format Version	Parquet file format version to use.
Parquet Row Group Size (bytes)	Maximum size in bytes of a row group being buffered in memory. The size of a row group is defined by the batch size, but you can limit it to restrict the memory usage for the write.
Parquet Page Size (bytes)	Page size in bytes for compressed pages.
Parquet Max Padding Size (bytes)	Maximum size in bytes of allowed padding to align rows.
Enable Parquet Dictionary Encoding	Enables Parquet dictionary encoding. There is one dictionary page per column per group when dictionary encoding is enabled.
Parquet Dictionary Page Size (bytes)	Page size in bytes for dictionary pages.

For protobuf data, on the Data Format tab, configure the following properties:


Protobuf Property	Description
Protobuf Descriptor File	Descriptor file (.desc) to use. The descriptor file must be in the Data Collector resources directory, `$SDC_RESOURCES`. For more information about environment variables, see Data Collector Environment Configuration in the Data Collector documentation. For information about generating the descriptor file, see Protobuf Data Format Prerequisites.
Message Type	Fully-qualified name for the message type to use when writing data. Use the following format: `<package name>.<message type>`. Use a message type defined in the descriptor file.

For text data, on the Data Format tab, configure the following properties:


Text Property	Description
Text Field Path	Field that contains the text data to be written. All data must be incorporated into the specified field.
Record Separator	Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use `\r\n` to separate records. By default, the destination uses `\n`.
On Missing Field	When a record does not include the text field, determines whether the destination reports the missing field as an error or ignores the missing field.
Insert Record Separator if No Text	When configured to ignore a missing text field, inserts the configured record separator string to create an empty line. When not selected, discards records without the text field.
Charset	Character set to use when writing data.

For whole files, on the Data Format tab, configure the following properties:


Whole File Property	Description
File Name Expression	Expression to use for the file names. For tips on how to name files based on input file names, see Writing Whole Files.
File Exists	Action to take when a file of the same name already exists in the output directory. Use one of the following options: Send to Error - Handles the record based on stage error record handling. Overwrite - Overwrites the existing file.
Permissions Expression	Expression that defines the access permissions for output files. Expressions should evaluate to a symbolic or numeric/octal representation of the permissions you want to use. By default, with no specified expression, files use the default permissions of the destination system. To use the original source file access permissions, use the following expression: `${record:value('/fileInfo/permissions')}`
Include Checksum in Events	Includes checksum information in whole file event records. Use only when the destination generates event records.
Checksum Algorithm	Algorithm to generate the checksum.

For XML data, on the Data Format tab, configure the following properties:


XML Property	Description
Pretty Format	Adds indentation to make the resulting XML document easier to read. Increases the record size accordingly.
Validate Schema	Validates that the generated XML conforms to the specified schema definition. Records with invalid schemas are handled based on the error handling configured for the destination. Important: Regardless of whether you validate the XML schema, the destination requires the record in a specific format. For more information, see Record Structure Requirement.
XML Schema	The XML schema to use to validate records.