2014年9月27日星期六

How to install the Azure Cross-Platform Command-Line Interface

There are two ways to install the xplat-cli; using installer packages for Windows and OS X, or if Node.js is installed on your system, the npm command.
For Linux systems, you must have Node.js installed and either use npm to install the xplat-cli as described below, or build it from source. The source is available at http://go.microsoft.com/fwlink/?linkid=253472&clcid=0x409. For more information on on building from source, see the INSTALL file included in the archive.
Once the xplat-cli has been installed, you will be able to use the azure command from your command-line interface (Bash, Terminal, Command prompt) to access the xplat-cli commands.

Using an installer

The following installer packages are available:

Using npm

If Node.js is installed on your system, use the following command to install the xplat-cli:
npm install azure-cli -g
This will install the xplat-cli and required dependencies. At the end of the installation, you should see something similar to the following:
azure-cli@0.8.0 ..\node_modules\azure-cli
|-- easy-table@0.0.1
|-- eyes@0.1.8
|-- xmlbuilder@0.4.2
|-- colors@0.6.1
|-- node-uuid@1.2.0
|-- async@0.2.7
|-- underscore@1.4.4
|-- tunnel@0.0.2
|-- omelette@0.1.0
|-- github@0.1.6
|-- commander@1.0.4 (keypress@0.1.0)
|-- xml2js@0.1.14 (sax@0.5.4)
|-- streamline@0.4.5
|-- winston@0.6.2 (cycle@1.0.2, stack-trace@0.0.7, async@0.1.22, pkginfo@0.2.3, request@2.9.203)
|-- kuduscript@0.1.2 (commander@1.1.1, streamline@0.4.11)
|-- azure@0.7.13 (dateformat@1.0.2-1.2.3, envconf@0.0.4, mpns@2.0.1, mime@1.2.10, validator@1.4.0, xml2js@0.2.8, wns@0.5.3, request@2.25.0)

How to connect to your Azure subscription

While some commands provided by the xplat-cli will work without an Azure subscription, most commands require a subscription. To configure the xplat-cli to work with your subscription you can either:
  • Download and use a publish settings file.
OR
  • Log in to Azure using an organizational account. When you log in, Azure Active Directory is used to authenticate the credentials.
To help you choose the authentication method that's appropriate for your needs, consider the following:
  • The log in method can make it easier to manage access to subscription, but may disrupt automation, as the credentials may time out and require you to log in again.
  • The publish settings file method installs a certificate that allows you to perform management tasks for as long as the subscription and the certificate are valid. This method makes it easier to use automation for long-running tasks. After you download and import the information, you don't need to provide it again. However, this method makes it harder to manage access to a subscription as anyone with access to the certificate can manage the subscription.
For more information about authentication and subscription management, see "What's the difference between account-based authentication and certificate-based authentication".
If you don't have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Use the log in method

To log in using an organizational account, use the following command:
azure login [username] [password]
To log out, use the following command:
azure logout [username]

Use the publish settings file method

To download the publish settings for your account, use the following command:
azure account download
This will open your default browser and prompt you to sign in to the Azure Management Portal. After signing in, a.publishsettings file will be downloaded. Make note of where this file is saved.
Next, import the .publishsettings file by running the following command, replacing [path to .publishsettings file] with the path to your .publishsettings file:
azure account import [path to .publishsettings file]
After importing your publish settings, you should delete the .publishsettings file, as it is no longer required by the Command-Line Tools and presents a security risk as it can be used to gain access to your subscription.

Multiple subscriptions

If you have multiple Azure subscriptions, logging in will grant access to all subscriptions associated with your credentials. If using a publish settings file, the .publishsettings file will contain information for all subscriptions. With either method, one subscription will be selected as the default subscription used by the xplat-cli when performing operations. You can view the subscriptions, as well as which one is the default, but using the azure account list command. This command will return information similar to the following:
info:    Executing command account list
data:    Name              Id                                    Current
data:    ----------------  ------------------------------------  -------
data:    Azure-sub-1       ####################################  true
data:    Azure-sub-2       ####################################  false
In the above list, the Current column indicates the current default subscription as Azure-sub-1. To change the default subscription, use the azure account set command, and specify the subscription that you wish to be the default. For example:
azure account set Azure-sub-2
This will change the default subscription to Azure-sub-2.
If you wish to use a non-default subscription with the xplat-cli, but don't want to change the current default, you can use the --subscription option and provide the name of the subscription you wish to use for the operation.

How use the Azure Cross-Platform Command-Line Interface

The xplat-cli is accessed using the azure command. To see a list of commands available, use the azure command with no parameters. You should see help information similar to the following:
info:             _    _____   _ ___ ___
info:            /_\  |_  / | | | _ \ __|
info:      _ ___/ _ \__/ /| |_| |   / _|___ _ _
info:    (___  /_/ \_\/___|\___/|_|_\___| _____)
info:       (_______ _ _)         _ ______ _)_ _
info:              (______________ _ )   (___ _ _)
info:
info:    Windows Azure: Microsoft's Cloud Platform
info:
info:    Tool version 0.8.0
help:
help:    Display help for a given command
help:      help [options] [command]
help:
help:    Opens the portal in a browser
help:      portal [options]
help:
help:    Commands:
help:      account        Commands to manage your account information and publish settings
help:      config         Commands to manage your local settings
help:      hdinsight      Commands to manage your HDInsight accounts
help:      mobile         Commands to manage your Mobile Services
help:      network        Commands to manage your Networks
help:      sb             Commands to manage your Service Bus configuration
help:      service        Commands to manage your Cloud Services
help:      site           Commands to manage your Web Sites
help:      sql            Commands to manage your SQL Server accounts
help:      storage        Commands to manage your Storage objects
help:      vm             Commands to manage your Virtual Machines
help:
help:    Options:
help:      -h, --help     output usage information
help:      -v, --version  output the application version
The top level commands listed above contain commands for working with a specific area of Azure. For example, the azure account command contains commands that relate to your Azure subscription, such as the download and import settings used previously.
Most commands are formatted as azure <command> <operation> [parameters] and perform an operation on a service or object such as your account configuration. Other commands provide sub-commands and follow the format azure <command> <subcommand> <operation> [parameters]. The following are example commands that work with your account configuration:
  • To view subscriptions that you have imported, use:
    azure account list
  • If you have imported subscriptions, use the following to set one as default:
    azure account set <subscription>
The --help or -h parameter can be used to view help for specific commands. Alternately, The azure help [command] [options] format can also be used to return the same information. For example, the following commands all return the same information:
azure account set --help

azure account set -h

azure help account set
When in doubt about the parameters needed by a command, refer to help using --help, -h or azure help [command].

Setting the configuration mode

The xplat-cli allows you to perform management operations on individual resources, which are user-managed entities such as a database server, database, or website. This is the default mode of operation for the xplat-cli, and is referred to as Azure Service Management. However, when you have a complex solution that consists of multiple resources, it is useful to be able to manage the entire solution as a single unit.
To support managing a group of resources as a single logical unit, or resource group, we have introduced a preview of theResource Manager as a new way of managing Azure resources.
To support the new Resource Manager, the xplat-cli allows you to switch between these management 'modes' using the azure config mode command.
The xplat-cli defaults to Azure Service Management mode. To switch to Resource Manager mode, use the following to enable command:
azure config mode arm
To change back to Azure service management mode, use the following command:
azure config mode asm
For more information on working with the Resource Manager using the xplat-cli, see Using the Azure Cross-Platform Command-Line Interface with the Resource Manager.

Working with services in Azure service management mode

The xplat-cli allows you to easily manage Azure services. In this example, you will learn how to use the xplat-cli to manage an Azure Website.
  1. Use the following command to create a new Azure Website. Replace mywebsite with a unique name.
    azure site create mywebsite
    You will be prompted to specify the region that the website will be created in. Select a region that is geographically near you. After this command completes, the website will be available at http://mywebsite.azurewebsites.net (replacemywebsite with the name you specified.)
  2. Use the following command to list websites for your subscription:
    azure site list
    The list should contain the site created in the previous step.
  3. Use the following command to stop the website. Replace mywebsite with the site name.
    azure site stop mywebsite
    After the command completes, you can refresh the browser to verify that the site has been stopped.
  4. Use the following command to start the website. Replace mywebsite with the site name.
    azure site start mywebsite
    After the command completes, you can refresh the browser to verify that the site has been started.
  5. Use the following command to delete the website. Replace mywebsite with the site name.
    azure site delete mywebsite
    After the command completes, use the azure site list command to verify that the website no longer exists.

How to script the Azure Cross-Platform Command-Line Interface

While you can use the xplat-cli to manually issue commands, you can also create complex automation workflows by leveraging the capabilities of your command-line interpreter and other command-line utilities available on your system. For example, the following command will stop all running Azure Websites:
azure site list | grep 'Running' | awk '{system("azure site stop "$2)}'
This example pipes a list of websites to the grep command, which inspects each line for the string 'Running'. Any lines that match are then piped to the awk command, which calls azure site stop and uses the second column passed to it (the running site name) as the site name to stop.
While this demonstrates how you can chain commands together, you can also create more elaborate scripts using the scripting features provided by your command-line interpreter. Different command-line interpreters have different scripting features and syntax. Bash is probably the most widely used command-line interpreter for UNIX-based systems, including Linux and OS X.
For information on scripting with Bash, see the Advanced Bash-Scripting Guide.
For more general information on scripting OS X or Linux-based systems, see Shell script.
For information on scripting Windows-based systems using batch files, see Command-line reference A-Z.

Understanding results

When creating scripts, you often need to capture the output of a command and either pass this to another command or perform an operation on the output such as checking for a specific value. The xplat-cli generates output to STDOUT and STDERR. Each line is prefixed by the strings info: for informational status messages, or data: for data returned about a service; however, you can instruct the xplat-cli to return more verbose information by using the --verbose or -v parameter. This will return additional information prefixed by the string verbose:.
For example, the following output is returned from the azure site list command:
info:    Executing command site list
+ Enumerating sites
data:    Name           Status   Mode  Host names
data:    -------------  -------  ----  -------------------------------
data:    myawesomesite  Running  Free  myawesomesite.azurewebsites.net
info:    site list command OK
If the --verbose or -v parameter is specified, information similar to the following is returned:
info:    Executing command site list
verbose: Subscription ####################################
verbose: Enumerating sites
verbose: [
verbose:     {
verbose:         ComputeMode: 'Shared',
verbose:         HostNameSslStates: {
verbose:             HostNameSslState: [
verbose:                 {
verbose:                     IpBasedSslResult: {
verbose:                         $: { i:nil: 'true' }
verbose:                     },
verbose:                     SslState: 'Disabled',
verbose:                     ToUpdateIpBasedSsl: {
verbose:                         $: { i:nil: 'true' }
verbose:                     },
verbose:                     VirtualIP: {
verbose:                         $: { i:nil: 'true' }
verbose:                     },
verbose:                     Thumbprint: {
verbose:                         $: { i:nil: 'true' }
verbose:                     },
verbose:                     ToUpdate: {
verbose:                         $: { i:nil: 'true' }
verbose:                     },
verbose:                     Name: 'myawesomesite.azurewebsites.net'
verbose:                 },
...
verbose:     }
verbose: ]
data:    Name           Status   Mode  Host names
data:    -------------  -------  ----  -------------------------------
data:    myawesomesite  Running  Free  myawesomesite.azurewebsites.net
info:    site list command OK
Note that the verbose: information appears to be JSON formatted data. You can use the --json parameter to return the information in JSON format if you are working with utilities that natively understand JSON, such as jsawk or jq. For example:
azure site list --json | jsawk -n 'out(this.Name)' | xargs -L 1 azure site delete -q
The command above retrieves a list of websites as JSON, then uses jsawk to retrieve the site names, and finally uses xargs to run a site delete command for each site, passing the site name as a parameter.

Working with errors

While the xplat-cli does log error information to STDERR, additional information on errors may also be logged to an azure.errfile in the directory that the script was ran from. If information is logged to this file, the following will be written to STDOUT:
info:    Error information has been recorded to azure.err

Exit status

Some of the xplat-cli commands do not return a non-zero exit status if required parameters are missing. Instead, they will prompt for user input. For example, when using the azure site create command to create a new website, if no site name or--location parameter are specified you will be prompted to supply these values.
If you are writing a script that relies on the exit status, please verify that the xplat-cli commands you are using do not prompt for user input.

Additional resources

发帖者 时间： 没有评论:
订阅： 博文 (Atom)