Skip to main content

Importing from Azure Blob Storage

Import bulk data files directly from Azure Blob Storage

Written by Michael Fatica

MetaLocator supports importing location data directly from Microsoft Azure Blob Storage. This allows you to store your CSV data files in an Azure Storage container and import them into MetaLocator either on-demand or on a recurring schedule.

Getting Your Azure Credentials

Option A: SAS Token (Recommended)

A SAS token provides scoped, time-limited access to your storage container without exposing your full account key.

  1. Sign in to the Azure Portal

  2. Navigate to your Storage Account

  3. In the left menu, select Shared access signature (under Security + networking)

  4. Configure the SAS settings:

    • Allowed services: Blob

    • Allowed resource types: Container, Object

    • Allowed permissions: Read, List

    • Set an appropriate expiry date

  5. Click Generate SAS and connection string

  6. Copy the SAS token value (it starts with ?sv=)

Option B: Account Key

The account key provides full access to all containers in your storage account.

  1. Sign in to the Azure Portal

  2. Navigate to your Storage Account

  3. In the left menu, select Access keys (under Security + networking)

  4. Click Show next to one of the keys

  5. Copy the Key value (a Base64-encoded string)

Security Note: SAS tokens are recommended over account keys because they can be scoped to specific containers, limited to read-only access, and set to expire after a defined period.

Step-by-Step Import Guide

Step 1: Start the Import

  1. Log in to your MetaLocator admin panel

  2. Navigate to the Import section

  3. Click the MS Azure Blob Storage button

Step 2: Enter Connection Details

Fill in the following fields on the Azure Blob Storage configuration form:

Field

Description

Example

Storage Account Name

The name of your Azure storage account (not the full URL)

mystorageaccount

Container Name

The name of the blob container holding your files

my-container

Authentication Method

Choose between SAS Token or Account Key

—

SAS Token

Your SAS token (if using SAS authentication)

?sv=2023-01-03&ss=b&srt=sco&sp=rl...

Account Key

Your account key (if using Account Key authentication)

(Base64-encoded string)

Step 3: Choose a File Selection Mode

MetaLocator provides two ways to select which Azure Blob Storage file or files should be imported.
​

Select File Mode

Use this mode when you want to select a specific file from the container.

  1. Select Select File as the file selection mode.

  2. Optionally enter a Path Prefix to limit the file list to a specific folder.

  3. Click Test Connection & Load Files.

  4. Select the desired CSV file from the resulting list.

A Path Prefix represents an Azure Blob Storage virtual folder. Enter it without a leading slash.

For example:

  • data/ selects files located directly inside the data folder.

  • /data/ should not be used.

  • Files in data/archive/ are not considered to be directly inside data/.

File Mask Mode

Use File Mask mode when uploaded files follow a predictable naming convention.

Enter a filename pattern in the File Mask field. File masks apply to the filename only and support the following wildcard characters:

  • * matches any number of characters.

  • ? matches exactly one character.

Examples:

  • partnerlocator*.csv matches partnerlocator.csv, partnerlocator-2026.csv, and similar filenames.

  • locations-2026-07-??.csv matches filenames such as locations-2026-07-01.csv.

The optional Path Prefix determines the exact virtual folder in which MetaLocator searches. The file mask should not include the folder path.

For example:

  • Path Prefix: incoming/

  • File Mask: locations-*.csv

This configuration considers files such as incoming/locations-2026-07-27.csv. It does not consider matching files in the container root or in a nested folder such as incoming/archive/.
​

After entering the Path Prefix and File Mask, click Test Connection & Load Files to preview the matching files.
​

MetaLocator evaluates up to 5,000 blobs returned by Azure for the configured prefix. Use a sufficiently specific Path Prefix and File Mask so that the candidate set remains below this limit.

Recommended File Naming Convention

Use a unique, timestamped filename for each file uploaded for Queue mode. A recommended format is locatorYYYY_MM_DD_HH_MM_SS.csv, such as locator2026_07_27_17_52_13.csv. Placing the date and time in year-to-second order keeps filenames naturally sortable and prevents a newly uploaded file from reusing the name of a file that MetaLocator has already processed. Generate timestamps using a consistent timezone, preferably UTC, and use zero-padded values so every filename follows the same structure.
​

Selecting the Most Recent Matching File

When Process as a Queue is not enabled, File Mask mode selects the most recently modified matching file.
​

The same most recent file is selected each time the job runs, including recurring scheduled runs. This mode is appropriate when your integration continually replaces or updates a current source file, or when only the newest dated file should represent the complete current dataset.
​

The matching-file preview displays up to 10 of the most recent matching files. The file marked Will be imported is the file MetaLocator will select.
​

Processing Matching Files as a Queue

Enable Process as a Queue when each matching file represents a separate batch that must be imported once and in chronological order.
​

In Queue mode, MetaLocator:

  • Sorts matching files by their Azure last-modified date.

  • Selects the oldest file that has not already been handled by this import job.

  • Imports files from oldest to newest.

  • Processes a maximum of 10 files during a single job run.

  • Continues with any remaining files during the next scheduled run.

When all matching files have already been processed, the job completes successfully without importing another file. It checks for new files the next time the job runs.


The matching-file preview displays the first 10 files that Queue mode will consider. The oldest file is marked Will be processed first.
​

Queue mode is intended for controlled inbound queues. Do not allow the number of candidate blobs for the configured Path Prefix and File Mask to reach 5,000. If Azure returns the 5,000-file limit while Queue mode is active, MetaLocator stops the import and sends a background-import failure notification because it cannot safely determine whether additional files exist beyond the returned results.
​

Step 4: Test the Connection

After entering your credentials and file selection settings, click Test Connection & Load Files to verify:

  • Your credentials are valid

  • The container is accessible

  • CSV files are available at the specified location

If the connection is successful, you will see a confirmation message indicating how many file(s) were found. If there is an error, a message will describe the issue (e.g., invalid credentials, container not found).

Step 5: Start the Import

  1. Once your file is selected and the connection is verified, click Next

  2. The import will begin as a background job

  3. A progress indicator will show the status of your import

  4. When complete, you will see a confirmation message

Keeping Data in Sync (Recurring Imports)

If your plan supports background processing, you will see a Keep Azure Blob Data In Sync? checkbox on the configuration form.

Enabling this option will:

  • Create a recurring background job that runs automatically every 24 hours

  • Download the latest file from your Azure container using the same connection settings and file selection criteria

  • Import the data into MetaLocator, keeping your location data up to date with changes in your source file

This is particularly useful when combined with File Mask mode, as it will always pick up the most recently modified file matching your pattern.

Troubleshooting

Connection Errors

Error

Cause

Solution

Authentication failed (HTTP 403)

Invalid or expired credentials

Verify your SAS token has not expired and has read+list permissions, or verify your account key is correct

Container not found (HTTP 404)

Incorrect container name or storage account name

Double-check the storage account name and container name for typos

Connection error

Network or DNS issue

Verify the storage account name is correct and the account is accessible

No Files Found

  • Ensure your CSV files have a .csv file extension

  • If using a path prefix, confirm the prefix matches the folder structure in your container (e.g., data/ not /data/)

  • If using file mask mode, verify your wildcard pattern matches the file naming convention

Import Fails After Download

  • Verify that your CSV file is properly formatted with column headers in the first row

  • Check that the file is not empty or corrupted

  • Review the import job status in the Jobs section of the admin panel for detailed error messages

SAS Token Expiration

SAS tokens have an expiry date. If your recurring import stops working, check whether your SAS token has expired and generate a new one if needed. When updating the SAS token:

  1. Navigate to the Import section

  2. Select Azure Blob Storage

  3. Enter the new SAS token

  4. Click Test Connection & Load Files to verify

  5. Proceed with the import to update the saved credentials

Supported File Format

Azure Blob Storage import supports CSV files only. Your CSV file should:

  • Have column headers in the first row

  • Use standard CSV formatting (comma-separated values)

  • Have a .csv file extension

Best Practices

  1. Use SAS tokens instead of account keys for better security

  2. Set SAS token expiry dates that are reasonable for your use case and renew them before they expire

  3. Create a container specifically for MetaLocator

  4. Use file masks for recurring imports to automatically pick up the latest file

  5. Organize files with path prefixes to keep your container organized and make file selection easier

  6. Test the connection before starting each import to catch credential or access issues early
    ​

Related Articles
Did this answer your question?