Azure Synapse Artifacts Client Library

0.22.0 · active · verified Thu Apr 09

The Microsoft Azure Synapse Artifacts Client Library for Python allows interaction with Azure Synapse Analytics workspaces to manage data factory artifacts like pipelines, datasets, linked services, and data flows. As of its current version 0.22.0, it provides a programmatic interface for creating, reading, updating, and deleting these resources. The library follows the Azure SDK guidelines for Python, utilizing `azure-core` and `azure-identity` for consistent interaction and authentication. New versions are released as part of the broader Azure SDK for Python release train, typically on a monthly or bi-monthly cadence, with `0.x.x` versions indicating a preview status.

Warnings

breaking The library is currently in a preview (0.x.x) version. APIs are subject to change without notice before a 1.0.0 stable release, which may introduce breaking changes in future minor versions.
Fix: Be prepared for potential API changes when upgrading. Monitor release notes closely for updates and consider pinning to specific preview versions in production environments until 1.0.0 is released.
gotcha The Synapse workspace endpoint URL must be in the correct format, typically `https://{workspace_name}.dev.azuresynapse.net`. Incorrect URLs (e.g., missing `.dev` or `.net`) will lead to connection errors.
Fix: Always verify the endpoint format from your Synapse workspace overview in the Azure portal or by inspecting the workspace properties. Set the `endpoint` parameter of `SynapseArtifactsClient` accordingly.
gotcha Using `DefaultAzureCredential` for authentication requires proper configuration of Azure environment variables (e.g., `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` for a service principal, or local login via `az login`).
Fix: Refer to the `azure-identity` documentation for setting up `DefaultAzureCredential`. Ensure the identity used has sufficient permissions (e.g., 'Synapse Contributor' or 'Synapse Artifact User') on the Synapse workspace.

Install

pip install azure-synapse-artifacts Install stable version

Imports

SynapseArtifactsClient
```
from azure.synapse.artifacts import SynapseArtifactsClient
```
The client for artifacts is directly under `azure.synapse.artifacts`, not an older 'data_factory' submodule or a top-level 'synapse' module.

DefaultAzureCredential

from azure.identity import DefaultAzureCredential

Quickstart

This quickstart demonstrates how to initialize the `SynapseArtifactsClient` using `DefaultAzureCredential` and list the pipelines within your Azure Synapse Analytics workspace. Ensure your `AZURE_SYNAPSE_WORKSPACE_URL` environment variable is set to your workspace's development endpoint (e.g., `https://{workspace_name}.dev.azuresynapse.net`) and your Azure credentials are configured for `DefaultAzureCredential` to function, typically via environment variables like `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` for service principals.

import os
from azure.identity import DefaultAzureCredential
from azure.synapse.artifacts import SynapseArtifactsClient

# Set your Synapse workspace endpoint. It should look like: https://{workspace_name}.dev.azuresynapse.net
synapse_workspace_url = os.environ.get('AZURE_SYNAPSE_WORKSPACE_URL', 'https://your-synapse-workspace.dev.azuresynapse.net')

if not synapse_workspace_url:
    raise ValueError("Please set the 'AZURE_SYNAPSE_WORKSPACE_URL' environment variable.")

try:
    # Authenticate with DefaultAzureCredential
    credential = DefaultAzureCredential()

    # Create a SynapseArtifactsClient
    client = SynapseArtifactsClient(endpoint=synapse_workspace_url, credential=credential)

    print(f"Connected to Synapse workspace: {synapse_workspace_url}")

    # List pipelines in the workspace
    print("Listing pipelines:")
    pipelines = client.pipeline.get_pipelines_by_workspace()
    for pipeline in pipelines:
        print(f"  - {pipeline.name}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure 'AZURE_SYNAPSE_WORKSPACE_URL' is set and your Azure credentials are configured.")
    print("For DefaultAzureCredential, ensure AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET (or other auth methods) are set.")

view raw JSON →