-->

Azure Data Lake Storage Massively scalable. Azure Data Explorer Fast and highly scalable data exploration service. Thanks for downloading the Azure SDK for Mac. This page provides resources to help you get started using the Azure SDK for node.js, PHP, or Python.

Using Azure Cosmos DB in Azure Storage Explorer enables users to manage Azure Cosmos DB entities, manipulate data, update stored procedures and triggers along with other Azure entities like Storage blobs and queues. Now you can use the same tool to manage your different Azure entities in one place. At this time, Azure Storage Explorer supports Cosmos accounts configured for SQL, MongoDB, Graph, and Table APIs.

Prerequisites

A Cosmos account with SQL API or Azure Cosmos DB's API for MongoDB. If you don't have an account, you can create one in the Azure portal, as described in Azure Cosmos DB: Build a SQL API web app with .NET and the Azure portal.

Installation

Install the newest Azure Storage Explorer bits here: Azure Storage Explorer, now we support Windows, Linux, and MAC version.

Connect to an Azure subscription

1. After installing the Azure Storage Explorer, click the plug-in icon on the left as shown in the following image:

2. Select Add an Azure Account, and then click Sign-in.

3. In the Azure Sign in dialog box, select Sign in, and then enter your Azure credentials.

4. Select your subscription from the list and then click Apply.

   The Explorer pane updates and displays the accounts in the selected subscription.

   You have successfully connected to your Cosmos DB account to your Azure subscription.

Connect to Azure Cosmos DB by using a connection string

An alternative way of connecting to an Azure Cosmos DB is to use a connection string. Use the following steps to connect using a connection string.

1. Find Local and Attached in the left tree, right-click Cosmos DB Accounts, choose Connect to Cosmos DB...

2. Only support SQL and Table API currently. Choose API, paste Connection String, input Account label, click Next to check the summary, and then click Connect to connect Azure Cosmos DB account. For information on retrieving the primary connection string, see Get the connection string.

Connect to Azure Cosmos DB by using local emulator

Use the following steps to connect to an Azure Cosmos DB by Emulator, only support SQL account currently.

1. Install Emulator and launch. For how to install Emulator, seeCosmos DB Emulator

2. Find Local and Attached in the left tree, right-click Cosmos DB Accounts, choose Connect to Cosmos DB Emulator...

3. Only support SQL API currently. Paste Connection String, input Account label, click Next to check the summary, and then click Connect to connect Azure Cosmos DB account. For information on retrieving the primary connection string, see Get the connection string.

Azure Cosmos DB resource management

You can manage an Azure Cosmos DB account by doing following operations:

• Open the account in the Azure portal
• Add the resource to the Quick Access list
• Search and refresh resources
• Create and delete databases
• Create and delete collections
• Create, edit, delete, and filter documents
• Manage stored procedures, triggers, and user-defined functions

Quick access tasks

By right-clicking on a subscription in the Explorer pane, you can perform many quick action tasks:

• Right-click an Azure Cosmos DB account or a database, you can choose Open in Portal and manage the resource in the browser on the Azure portal.

• You can also add Azure Cosmos DB account, database, collection to Quick Access.

• Search from Here enables keyword search under the selected path.

Database and collection management

Create a database

• Right-click the Azure Cosmos DB account, choose Create Database, input the database name, and press Enter to complete.

Delete a database

• Right-click the database, click Delete Database, and click Yes in the pop-up window. The database node is deleted, and the Azure Cosmos DB account refreshes automatically.

Create a collection

1. Right-click your database, choose Create Collection, and then provide the following information like Collection ID, Storage capacity, etc. Click OK to finish.

2. Select Unlimited to be able to specify partition key, then click OK to finish.

   If a partition key is used when creating a collection, once creation is completed, the partition key value can't be changed on the collection.

Delete a collection

• Right-click the collection, click Delete Collection, and then click Yes in the pop-up window.

  The collection node is deleted, and the database refreshes automatically.

Download Azure Explorer

Document management

Create and modify documents

• To create a new document, open Documents in the left window, click New Document, edit the contents in the right pane, then click Save. You can also update an existing document, and then click Save. Changes can be discarded by clicking Discard.

Delete a document

• Click the Delete button to delete the selected document.

Query for documents

• Edit the document filter by entering a SQL query and then click Apply.

Graph management

Create and modify vertex

1. To create a new vertex, open Graph from the left window, click New Vertex, edit the contents, then click OK.

2. To modify an existing vertex, click the pen icon in the right pane.

Delete a graph

• To delete a vertex, click the recycle bin icon beside the vertex name.

Filter for graph

• Edit the graph filter by entering a gremlin query and then click Apply Filter.

Table management

Create and modify table

1. To create a new table, open Entities from the left window, click Add, edit the content in Add Entity dialog, add property by clicking button Add Property, then click Insert.

2. To modify a table, click Edit, modify the content, then click Update.

Import and export table

1. To import, click Import button and choose an existing table.

2. To export, click Export button and choose a destination.

Delete entities

• Select the entities and click button Delete.

Query table

• Click Query button, input query condition, then click Execute Query button. Close Query pane by clicking Close Query button.

Manage stored procedures, triggers, and UDFs

• To create a stored procedure, in the left tree, right-click Stored Procedure, choose Create Stored Procedure, enter a name in the left, type the stored procedure scripts in the right window, and then click Create.

• You can also edit existing stored procedures by double-clicking, making the update, and then clicking Update to save, or click Discard to cancel the change.

• The operations for Triggers and UDF are similar with Stored Procedures.

Troubleshooting

Azure Cosmos DB in Azure Storage Explorer is a standalone app that allows you to connect to Azure Cosmos DB accounts hosted on Azure and Sovereign Clouds from Windows, macOS, or Linux. It enables you to manage Azure Cosmos DB entities, manipulate data, update stored procedures and triggers along with other Azure entities like Storage blobs and queues.

These are solutions for common issues seen for Azure Cosmos DB in Storage Explorer.

Sign in issues

Before proceeding further, try restarting your application and see if the problems can be fixed.

Self-signed certificate in certificate chain

There are a few reasons you may be seeing this error, the two most common ones are:

• You're behind a transparent proxy, which means someone (such as your IT department) is intercepting HTTPS traffic, decrypting it, and then encrypting it using a self-signed certificate.

• You're running software, such as anti-virus software, which is injecting a self-signed SSL certificates into the HTTPS messages you receive.

When Storage Explorer encounters one of these 'self-signed certificates', it can no longer know if the HTTPS message it's receiving has been tampered with. If you have a copy of the self-signed certificate though, then you can tell Storage Explorer to trust it. If you're unsure of who is injecting the certificate, then you can try to find it yourself by doing the following steps:

1. Install Open SSL
   • Windows (any of the light versions is ok)
   • Mac and Linux: Should be included with your operating system
2. Run Open SSL
   • Windows: Go to the install directory, then /bin/, then double-click on openssl.exe.
   • Mac and Linux: execute openssl from a terminal
3. Execute s_client -showcerts -connect microsoft.com:443
4. Look for self-signed certificates. If you're unsure, which are self-signed, then look for anywhere the subject ('s:') and issuer ('i:') are the same.
5. Once you have found any self-signed certificates, copy and paste everything from and including -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- to a new .cer file for each one.
6. Open Storage Explorer and then go to Edit > SSL Certificates > Import Certificates. Using the file picker, find, select, and open the .cer files you created.

If you're unable to find any self-signed certificates using the above steps, could send feedback for more help.

Unable to retrieve subscriptions

If you're unable to retrieve your subscriptions after you successfully signed in:

• Verify your account has access to the subscriptions by signing into the Azure Portal
• Make sure you have signed in using the correct environment (Azure, Azure China, Azure Germany, Azure US Government, or Custom Environment/Azure Stack)
• If you're behind a proxy, make sure that you have configured the Storage Explorer proxy properly
• Try removing and readding the account
• Try deleting the following files from your home directory (such as: C:UsersContosoUser), and then readding the account:
  • .adalcache
  • .devaccounts
  • .extaccounts
• Watch the developer tools console (f12) while signing in for any error messages

Unable to see the authentication page

If you're unable to see the authentication page:

• Depending on the speed of your connection, it may take a while for the sign-in page to load, wait at least one minute before closing the authentication dialog
• If you're behind a proxy, make sure that you have configured the Storage Explorer proxy properly
• Bring up the developer console by pressing F12 key. Watch the responses from developer console and see if you can find any clue for why authentication is not working

Cannot remove account

If you're unable to remove an account, or if the reauthenticate link does not do anything

• Try deleting the following files from your home directory, and then readding the account:
  • .adalcache
  • .devaccounts
  • .extaccounts
• If you want to remove SAS attached Storage resources, delete:
  • %AppData%/StorageExplorer folder for Windows
  • /Users/<your_name>/Library/Application SUpport/StorageExplorer for Mac
  • ~/.config/StorageExplorer for Linux
  • You will have to reenter all your credentials if you delete these files

Http/Https proxy issue

You cannot list Azure Cosmos DB nodes in left tree when configuring http/https proxy in ASE. It's a known issue, and will be fixed in next release. You could use Azure Cosmos DB data explorer in Azure portal as a work-around at this moment.

'Development' node under 'Local and Attached' node issue

There is no response after clicking the 'Development' node under 'Local and Attached' node in left tree. The behavior is expected. Azure Cosmos DB local emulator will be supported in next release.

Attaching Azure Cosmos DB account in 'Local and Attached' node error

If you see below error after attaching Azure Cosmos DB account in 'Local and Attached' node, then check if you're using the right connection string.

Expand Azure Cosmos DB node error

You may see below error while trying to expand the tree nodes in left.

Try the following suggestions:

• Check if the Azure Cosmos DB account is in provision progress and try again when the account is being created successfully.
• If the account is under 'Quick Access' node or 'Local and Attached' nodes, then check if the account has been deleted. If so, you need to remove the node manually.

Contact us

If none of the solutions work for you, send email to Azure Cosmos DB Dev Tooling Team (cosmosdbtooling@microsoft.com) with details about the issue, for fixing the issues.

Next steps

• Watch the following video to see how to use Azure Cosmos DB in Azure Storage Explorer: Use Azure Cosmos DB in Azure Storage Explorer.
• Learn more about Storage Explorer and connect more services in Get started with Storage Explorer.

AzCopy is a command-line utility that you can use to copy blobs or files to or from a storage account. This article helps you download AzCopy, connect to your storage account, and then transfer files.

Note

AzCopy V10 is the currently supported version of AzCopy.

If you need to use AzCopy v8.1, see the Use the previous version of AzCopy section of this article.

Download AzCopy

First, download the AzCopy V10 executable file to any directory on your computer. AzCopy V10 is just an executable file, so there's nothing to install.

• Windows 64-bit (zip)
• Windows 32-bit (zip)
• Linux (tar)
• MacOS (zip)

These files are compressed as a zip file (Windows and Mac) or a tar file (Linux). To download and decompress the tar file on Linux, see the documentation for your Linux distribution.

Note

If you want to copy data to and from your Azure Table storage service, then install AzCopy version 7.3.

Run AzCopy

For convenience, consider adding the directory location of the AzCopy executable to your system path for ease of use. That way you can type azcopy from any directory on your system.

If you choose not to add the AzCopy directory to your path, you'll have to change directories to the location of your AzCopy executable and type azcopy or .azcopy in Windows PowerShell command prompts.

To see a list of commands, type azcopy -h and then press the ENTER key.

To learn about a specific command, just include the name of the command (For example: azcopy list -h).

To find detailed reference documentation for each command and command parameter, see azcopy

Note

As an owner of your Azure Storage account, you aren't automatically assigned permissions to access data. Before you can do anything meaningful with AzCopy, you need to decide how you'll provide authorization credentials to the storage service.

Choose how you'll provide authorization credentials

You can provide authorization credentials by using Azure Active Directory (AD), or by using a Shared Access Signature (SAS) token.

Use this table as a guide:

Option 1: Use Azure Active Directory

By using Azure Active Directory, you can provide credentials once instead of having to append a SAS token to each command.

Note

In the current release, if you plan to copy blobs between storage accounts, you’ll have to append a SAS token to each source URL. You can omit the SAS token only from the destination URL. For examples, see Copy blobs between storage accounts.

The level of authorization that you need is based on whether you plan to upload files or just download them.

If you just want to download files, then verify that the Storage Blob Data Reader has been assigned to your user identity, managed identity, or service principal.

User identities, managed identities, and service principals are each a type of security principal, so we'll use the term security principal for the remainder of this article.

If you want to upload files, then verify that one of these roles has been assigned to your security principal:

These roles can be assigned to your security principal in any of these scopes:

• Container (file system)
• Storage account
• Resource group
• Subscription

To learn how to verify and assign roles, see Grant access to Azure blob and queue data with RBAC in the Azure portal.

Note

Keep in mind that RBAC role assignments can take up to five minutes to propagate.

You don't need to have one of these roles assigned to your security principal if your security principal is added to the access control list (ACL) of the target container or directory. In the ACL, your security principal needs write permission on the target directory, and execute permission on container and each parent directory.

To learn more, see Access control in Azure Data Lake Storage Gen2.

Authenticate a user identity

After you've verified that your user identity has been given the necessary authorization level, open a command prompt, type the following command, and then press the ENTER key.

If you belong to more than one organization, include the tenant ID of the organization to which the storage account belongs.

Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

This command returns an authentication code and the URL of a website. Open the website, provide the code, and then choose the Next button.

A sign-in window will appear. In that window, sign into your Azure account by using your Azure account credentials. After you've successfully signed in, you can close the browser window and begin using AzCopy.

Authenticate a service principal

This is a great option if you plan to use AzCopy inside of a script that runs without user interaction, particularly when running on-premises. If you plan to run AzCopy on VMs that run in Azure, a managed service identity is easier to administer. To learn more, see the Authenticate a managed identity section of this article.

Before you run a script, you have to sign-in interactively at least one time so that you can provide AzCopy with the credentials of your service principal. Those credentials are stored in a secured and encrypted file so that your script doesn't have to provide that sensitive information.

You can sign into your account by using a client secret or by using the password of a certificate that is associated with your service principal's app registration.

To learn more about creating service principal, see How to: Use the portal to create an Azure AD application and service principal that can access resources.

To learn more about service principals in general, see Application and service principal objects in Azure Active Directory

Using a client secret

Start by setting the AZCOPY_SPA_CLIENT_SECRET environment variable to the client secret of your service principal's app registration.

Note

Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. That way, the value is available only to the current session.

This example shows how you could do this in PowerShell.

Note

Consider using a prompt as shown in this example. That way, your password won't appear in your console's command history.

Next, type the following command, and then press the ENTER key.

Replace the <application-id> placeholder with the application ID of your service principal's app registration. Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

Using a certificate

If you prefer to use your own credentials for authorization, you can upload a certificate to your app registration, and then use that certificate to login.

In addition to uploading your certificate to your app registration, you'll also need to have a copy of the certificate saved to the machine or VM where AzCopy will be running. This copy of the certificate should be in .PFX or .PEM format, and must include the private key. The private key should be password-protected. If you're using Windows, and your certificate exists only in a certificate store, make sure to export that certificate to a PFX file (including the private key). For guidance, see Export-PfxCertificate

Next, set the AZCOPY_SPA_CERT_PASSWORD environment variable to the certificate password.

Note

Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. That way, the value is available only to the current session.

This example shows how you could do this task in PowerShell.

Next, type the following command, and then press the ENTER key.

Windows Azure Storage Explorer Download

Replace the <path-to-certificate-file> placeholder with the relative or fully-qualified path to the certificate file. AzCopy saves the path to this certificate but it doesn't save a copy of the certificate, so make sure to keep that certificate in place. Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

Note

Microsoft Azure Storage Explorer Download For Mac Os X

Consider using a prompt as shown in this example. That way, your password won't appear in your console's command history.

Authenticate a managed identity

This is a great option if you plan to use AzCopy inside of a script that runs without user interaction, and the script runs from an Azure Virtual Machine (VM). When using this option, you won't have to store any credentials on the VM.

You can sign into your account by using the a system-wide managed identity that you've enabled on your VM, or by using the client ID, Object ID, or Resource ID of a user-assigned managed identity that you've assigned to your VM.

To learn more about how to enable a system-wide managed identity or create a user-assigned managed identity, see Configure managed identities for Azure resources on a VM using the Azure portal.

Using a system-wide managed identity

First, make sure that you've enabled a system-wide managed identity on your VM. See System-assigned managed identity.

Then, in your command console, type the following command, and then press the ENTER key.

Using a user-assigned managed identity

First, make sure that you've enabled a user-assigned managed identity on your VM. See User-assigned managed identity.

Then, in your command console, type any of the following commands, and then press the ENTER key.

Replace the <client-id> placeholder with the client ID of the user-assigned managed identity.

Replace the <object-id> placeholder with the object ID of the user-assigned managed identity.

Replace the <resource-id> placeholder with the resource ID of the user-assigned managed identity.

Option 2: Use a SAS token

You can append a SAS token to each source or destination URL that use in your AzCopy commands.

This example command recursively copies data from a local directory to a blob container. A fictitious SAS token is appended to the end of the of the container URL.

To learn more about SAS tokens and how to obtain one, see Using shared access signatures (SAS).

Transfer files

After you've authenticated your identity or obtained a SAS token, you can begin transferring files.

To find example commands, see any of these articles.

Use AzCopy in a script

Obtain a static download link

Over time, the AzCopy download link will point to new versions of AzCopy. If your script downloads AzCopy, the script might stop working if a newer version of AzCopy modifies features that your script depends upon.

To avoid these issues, obtain a static (un-changing) link to the current version of AzCopy. That way, your script downloads the same exact version of AzCopy each time that it runs.

To obtain the link, run this command:

Note

For Linux, --strip-components=1 on the tar command removes the top-level folder that contains the version name, and instead extracts the binary directly into the current folder. This allows the script to be updated with a new version of azcopy by only updating the wget URL.

Azure Storage Explorer Version

The URL appears in the output of this command. Your script can then download AzCopy by using that URL.

Escape special characters in SAS tokens

In batch files that have the .cmd extension, you'll have to escape the % characters that appear in SAS tokens. You can do that by adding an addition % character next to existing % characters in the SAS token string.

Run scripts by using Jenkins

If you plan to use Jenkins to run scripts, make sure to place the following command at the beginning of the script.

Use AzCopy in Azure Storage Explorer

Storage Explorer uses AzCopy to perform all of it's data transfer operations. You can use Storage Explorer if you want to leverage the performance advantages of AzCopy, but you prefer to use a graphical user interface rather than the command line to interact with your files.

Storage Explorer uses your account key to perform operations, so after you sign into Storage Explorer, you won't need to provide additional authorization credentials.

Use the previous version of AzCopy

If you need to use the previous version of AzCopy (AzCopy v8.1), see either of the following links:

Configure, optimize, and troubleshoot AzCopy

See Configure, optimize, and troubleshoot AzCopy

Next steps

If you have questions, issues, or general feedback, submit them on GitHub page.