Azure Synapse Management

Common errors

• ModuleNotFoundError: No module named 'azure.mgmt.synapse'

  cause This error typically occurs when the 'azure-mgmt-synapse' package is not installed in the Python environment, or if you are running code in an environment like an Azure Synapse Notebook where the package needs to be explicitly added to the Spark pool libraries or session.
  fix Install the package using pip: `pip install azure-mgmt-synapse`. If in a Synapse Notebook, ensure the package is added to the Spark pool's requirements.txt or installed via `%pip install azure-mgmt-synapse` in a notebook cell, followed by a session restart.

• ClientAuthenticationError: DefaultAzureCredential failed to retrieve a token from the included credentials.

  cause This error indicates that `DefaultAzureCredential` (from `azure-identity`) could not find valid credentials in the execution environment. This is common in Synapse notebooks, local development, or service deployments where the managed identity or environment variables are not correctly configured or lack necessary permissions.
  fix Ensure the Synapse workspace's managed identity has been granted appropriate permissions (e.g., Storage Blob Data Contributor) on target resources. If running locally, set environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID) or ensure `az login` is successful and authenticated to the correct tenant. For multi-tenant scenarios, consider passing `additionally_allowed_tenants=['*']` to `DefaultAzureCredential`.

• {"code":"InvalidRequestContent","message":"The request content was invalid and could not be deserialized: Required property 'name' not found in 'sku'."}

  cause This error occurs during Azure Synapse Workspace creation when the 'sku' object in the request payload (e.g., ARM template or SDK parameters) is missing the mandatory 'name' property, which defines the pricing tier and capabilities.
  fix Ensure that the `sku` object includes a `name` property with a valid SKU name (e.g., 'Standard' or a specific data warehouse SKU like 'DW100c') and that the casing is correct.

• AttributeError: 'Operations' object has no attribute 'query_pipeline_runs_by_workspace'

  cause This `AttributeError` typically means you are trying to call a method on a client's operations object that either doesn't exist, has been renamed, or is not available in the specific version of the SDK being used. It often points to an incorrect API call pattern.
  fix Consult the `azure-mgmt-synapse` SDK documentation for the correct method name and usage for your specific task (e.g., listing pipeline runs). The API structure or method names may have changed between SDK versions. For the specific `query_pipeline_runs_by_workspace` example, direct access via `client.operations.query_pipeline_runs_by_workspace` might be incorrect; it might be part of a different operation group or require different parameters.

• (MissingRequiredProperty) Missing required property 'properties' on entity

  cause This error occurs when creating or updating a Synapse resource (e.g., an integration runtime) via the SDK, and a required `properties` object within the resource's definition is missing or malformed in the request payload.
  fix Review the specific model definition for the resource you are creating (e.g., `ManagedIntegrationRuntime` or similar) in the `azure.mgmt.synapse.models` module. Ensure that all mandatory properties, including the top-level `properties` object and its nested required attributes, are correctly provided and populated with valid data.

Warnings

• breaking Breaking changes were introduced in version 2.0.0, significantly revamping the authentication and client interaction model. The legacy `azure.common.credentials` or `msrestazure.azure_active_directory` instances are no longer supported. The `credentials` parameter was renamed to `credential`.
  Fix: Migrate to `azure-identity` classes (e.g., `DefaultAzureCredential`) for authentication. Update client instantiation to pass a `credential` object and pass configuration as keyword arguments instead of a `config` attribute.
• breaking Long-running operations (LROs) that previously returned `msrest.polling.LROPoller` now return `azure.core.polling.LROPoller` and are typically prefixed with `begin_`.
  Fix: Adjust code to use the `begin_` prefix for LRO methods and expect `azure.core.polling.LROPoller` for polling results.
• breaking The exception hierarchy has been simplified. Most exceptions now derive from `azure.core.exceptions.HttpResponseError`, and `CloudError` has been removed.
  Fix: Update exception handling to catch `azure.core.exceptions.HttpResponseError` instead of `CloudError` or other specific legacy exceptions.
• breaking Model changes: `WorkspacePatchInfo` and `Workspace` models no longer have the `network_settings` parameter in version 2.0.0. Instead, `public_network_access` was added.
  Fix: Review model usage when updating or creating Synapse workspaces; adjust parameters for `WorkspacePatchInfo` and `Workspace` accordingly, using `public_network_access` if needed.
• gotcha Confusion between Python and .NET SDK status: The .NET NuGet package `Microsoft.Azure.Management.Synapse` is deprecated and no longer maintained. However, this Python library (`azure-mgmt-synapse`) remains active and supported. Users should ensure they are referencing the correct SDK for their language.
  Fix: Always verify the status and documentation for the specific language SDK being used. For Python, `azure-mgmt-synapse` is the current management library.

Install

• pip install azure-mgmt-synapse Install stable version

Imports

• SynapseManagementClient

  from azure.mgmt.synapse import SynapseManagementClient

• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

Quickstart

This quickstart demonstrates how to authenticate with Azure using `DefaultAzureCredential` and then list all Azure Synapse workspaces within a specified subscription using `SynapseManagementClient`.

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.synapse import SynapseManagementClient

# Set the AZURE_SUBSCRIPTION_ID environment variable or replace with your actual subscription ID
subscription_id = os.environ.get("AZURE_SUBSCRIPTION_ID", "<your-subscription-id>")

if subscription_id == "<your-subscription-id>":
    raise ValueError("Please set the AZURE_SUBSCRIPTION_ID environment variable or provide your subscription ID.")

# Authenticate using DefaultAzureCredential, which handles various Azure authentication methods.
# For local development, ensure you are logged in via Azure CLI (`az login`)
# or have appropriate environment variables set.
credential = DefaultAzureCredential()

# Create a SynapseManagementClient
client = SynapseManagementClient(credential, subscription_id)

print("Listing Synapse Workspaces:")
# Iterate over the workspaces in your subscription
for workspace in client.workspaces.list():
    print(f"- {workspace.name} (Location: {workspace.location})")