%azure.connect

  • Article

Warning

This documentation refers to the Classic QDK, which has been replaced by the Modern QDK.

The Modern QDK only supports the '%%qsharp' magic command.

Summary

Connects to an Azure Quantum workspace or displays current connection status.

Description

This magic command allows for connecting to an Azure Quantum workspace as specified by the resource ID and location of the workspace or by a combination of subscription ID, resource group name, workspace name, and location.

If the connection is successful, a list of the available Q# execution targets in the Azure Quantum workspace will be displayed.

Required parameters

The Azure Quantum workspace can be identified by resource ID:

  • resourceId=<string>: The resource ID of the Azure Quantum workspace. This can be obtained from the workspace page in the Azure portal. The resourceId= prefix is optional for this parameter, as long as the resource ID is valid.

Alternatively, it can be identified by subscription ID, resource group name, and workspace name:

  • subscription=<string>: The Azure subscription ID for the Azure Quantum workspace.
  • resourceGroup=<string>: The Azure resource group name for the Azure Quantum workspace.
  • workspace=<string>: The name of the Azure Quantum workspace.

Along with the identifiers above, a valid location is required.

  • location=<string>: The Azure region where the Azure Quantum workspace is provisioned. This may be specified as a region name such as "East US" or a location name such as "eastus".

Optional parameters

  • storage=<string>: The connection string to the Azure storage account. Required if the specified Azure Quantum workspace was not linked to a storage account at workspace creation time.
  • credential=<CredentialType>: The type of credentials to use to authenticate with Azure. NOTE: to authenticate we leverage the Azure Identity library, based on this parameter we will create an instance of a Credential Class. Possible options are:
    • Environment: Authenticates a service principal or user via credential information specified in environment variables.
    • ManagedIdentity: Authenticates the managed identity of an azure resource.
    • CLI: Authenticate in a development environment with the Azure CLI.
    • SharedToken: Authenticate using tokens in the local cache shared between Microsoft applications.
    • VisualStudio: Authenticate using data from Visual Studio.
    • VisualStudioCode: Authenticate in a development environment with Visual Studio Code.
    • Interactive: Opens a new browser window to interactively authenticate a user and obtain an access token.
    • DeviceCode: Authenticates a user using the device code flow to obtain an access token. If not provided, it will try each credential type in order and pick the first one that can succesfully authenticate with Azure.

Possible errors

  • WorkspaceNotFound: No Azure Quantum workspace was found that matches the specified criteria.
  • AuthenticationFailed: Failed to authenticate to the specified Azure Quantum workspace.

Examples for %azure.connect

Example 1

Connect to an Azure Quantum workspace using its resource ID to the 'West Us' region:

In []: %azure.connect "/subscriptions/.../Microsoft.Quantum/Workspaces/WORKSPACE_NAME" location="West US"
Out[]: Connected to Azure Quantum workspace WORKSPACE_NAME in location westus.
        <list of Q# execution targets available in the Azure Quantum workspace>

Example 2

Connect to an Azure Quantum workspace using its resource ID, a storage account connection string, and a location:

In []: %azure.connect resourceId="/subscriptions/.../Microsoft.Quantum/Workspaces/WORKSPACE_NAME"
                      storage="STORAGE_ACCOUNT_CONNECTION_STRING"
                      location="East US"
Out[]: Connected to Azure Quantum workspace WORKSPACE_NAME in location eastus.
        <list of Q# execution targets available in the Azure Quantum workspace>

Example 3

Connect to an Azure Quantum workspace using individual subscription ID, resource group name, using a browser to prompt for user credentials with Azure:

In []: %azure.connect subscription="SUBSCRIPTION_ID"
                      resourceGroup="RESOURCE_GROUP_NAME"
                      workspace="WORKSPACE_NAME"
                      location="West US"
                      credential="interactive"
Out[]: Connected to Azure Quantum workspace WORKSPACE_NAME in location westus.
        <list of Q# execution targets available in the Azure Quantum workspace>

Example 4

Print information about the currently-connected Azure Quantum workspace:

In []: %azure.connect
Out[]: Connected to Azure Quantum workspace WORKSPACE_NAME in location westus.
        <list of Q# execution targets available in the Azure Quantum workspace>