Configuring an ADF Linked Service Connection for Azure Files

note

For information on how to enable a connection for use with linked services, see Configuring a Linked Service Connection.

note

Field labels in this walkthrough follow the underlying Azure Data Factory property names, with the connection column that carries each value named alongside. The exact labels shown in the BimlFlex Connection Editor may differ.

After selecting Azure File Storage from the Linked Service Type dropdown, the form required for creating an Azure Files Linked Service will appear.

File Format Connections

Azure Files is selected as the Linked Service Type of a connection whose System Type is one of the file formats Delimited Format, Avro Format, Binary Format, JSON Format, ORC Format, Parquet Format or XML Format. The Azure File Storage option appears in the Linked Service Type dropdown when the connection's Connection Type is Azure File Server.

Choosing an Authentication Method

Method	Credentials	Additional Settings
Account Key	Connection String, with the Account Key in Azure Key Vault	fileShare, snapshot (optional)
Shared Access Signature	SAS URI, with the SAS Token in Azure Key Vault	fileShare, snapshot (optional)
Host, User Name and Password	Host, User Name and Password	None

Recommendation: Store the Account Key, the SAS Token and the Password in Azure Key Vault rather than entering them as plaintext.

Complete Example: Account Key with Azure Key Vault

Field	Example Value
Connect via Integration Runtime	AutoResolveIntegrationRuntime
Connection String	DefaultEndpointsProtocol=https;AccountName=contosofiles;
Azure Key Vault Linked Service (for Account Key)	bfx-kv
Secret Name (for Account Key)	BFX-LND-AzureFilesAccountKey
File Share (Additional Settings key fileShare)	landing

Required Fields

Common Required Fields

The required fields for an Azure Files Linked Service connection depend on the authentication method used. Connect via Integration Runtime names the integration runtime for every method.

• Connect via Integration Runtime

Authentication Method Dependent Required Fields

Required fields for Account Key:

• Connection String
• Account Key in Azure Key Vault, or the account key inside the Connection String
• File Share

Required fields for Shared Access Signature:

• SAS URI
• SAS Token in Azure Key Vault, when the SAS URI carries no token
• File Share

Required fields for Host, User Name and Password:

• Host
• User Name
• Password (or Azure Key Vault)

Optional fields for Account Key and Shared Access Signature are:

• Snapshot

Connect via Integration Runtime

Connect via Integration Runtime names the integration runtime for an Azure Files Linked Service connection. The default value is AutoResolveIntegrationRuntime. To use another runtime, select it from the dropdown or choose + New to add one. When a custom value is saved in the linked service form, it will be added to the custom integration runtimes. The custom values that appear in this dropdown can be maintained in Settings under Azure - AzureIntegrationRuntime.

The runtime is stored in the connection's LS_ConnectVia_IntegrationRuntime column. Any value other than AutoResolveIntegrationRuntime is written to the linked service as the runtime it connects through.

Authentication Method

The Azure Files Linked Service connection can use Account Key, Shared Access Signature, or Host, User Name and Password authentication. BimlFlex does not read the connection's Authentication Type column for this connector. The fields that are filled in decide the form. When the connection's LS_EncryptedCredential column holds an Encrypted Credential value, it is also written to the linked service. The connection form offers no Encrypted Credential field, so the LS_EncryptedCredential column is set outside the form.

Account Key

Account Key authentication connects with the storage account's connection string and account key.

The Connection String is entered as plaintext in the connection's LS_ConnectionString column and maps to the ADF connectionString property (for example, DefaultEndpointsProtocol=https;AccountName=contosofiles;). The Account Key is an Azure Key Vault reference held in the LS_AccountKeyKVS_ fields that resolves to the account key at runtime. It maps to the ADF accountKey property. When the account key is held in Azure Key Vault, the Connection String leaves the AccountKey part out.

note

It is suggested that Azure Key Vault be used for the Account Key in place of entering it in the Connection String.

Shared Access Signature

Shared Access Signature authentication connects with a shared access signature URI to the storage resources.

The SAS URI is entered as plaintext in the connection's LS_SasUri column and maps to the ADF sasUri property (for example, https://contosofiles.file.core.windows.net/). The SAS Token is an Azure Key Vault reference held in the LS_SasTokenKVS_ fields that resolves to the token at runtime. It maps to the ADF sasToken property. When the SAS Token is held in Azure Key Vault, the SAS URI leaves the token part out.

note

It is suggested that Azure Key Vault be used for the SAS Token in place of entering it in the SAS URI.

Host, User Name and Password

Host, User Name and Password authentication connects to the file share by its host name with the storage account name and the storage access key. Microsoft describes this form as the legacy model, which transfers data over Server Message Block (SMB), and suggests the Account Key or Shared Access Signature form in its place.

The Host is stored in the connection's LS_Host column and maps to the ADF host property. It takes the form \\<storage name>.file.core.windows.net\<file service name> (for example, \\contosofiles.file.core.windows.net\landing). The User Name is stored in the connection's LS_Username column and maps to the ADF userId property. It takes the form AZURE\<storage name> (for example, AZURE\contosofiles). The Password field accepts the storage access key as plaintext in the LS_Password column, or an Azure Key Vault reference held in the LS_PasswordKVS_ fields that resolves to the key at runtime. It maps to the ADF password property.

note

It is suggested that Azure Key Vault be used in place of manually entering the Password.

Credential

When the connection's LS_Credential column names a credential, it is written to the linked service as the ADF credential reference. The connection form offers no Credential field, so the LS_Credential column is set outside the form. Microsoft describes the credential reference as part of user-assigned managed identity authentication. The linked service carries no serviceEndpoint property.

File Share

The File Share names the Azure file share the connector reads from or writes to (for example, landing). It is required for the Account Key and Shared Access Signature forms.

The File Share is stored in the connection's Additional Settings (LS_AdditionalSettings) under the key fileShare, and maps to the ADF fileShare property.

Snapshot

The Snapshot names the date of a file share snapshot, when the copy reads from a snapshot rather than from the live share. It is optional.

The Snapshot is stored in the connection's Additional Settings (LS_AdditionalSettings) under the key snapshot, and maps to the ADF snapshot property. The value is written to the linked service as it is entered.

Azure Data Factory Linked Service Additional Information

For additional information on ADF Azure Files Linked Service and its connection requirements see the Azure Data Factory Azure Files Connector documentation.