Getting Started

Installation

Download via Maven snapshot repo:

<repositories>
  <repository>
    <id>adx-snapshots</id>
    <name>Azure ADX Snapshots</name>
    <url>http://adxsnapshots.azurewebsites.net/</url>
    <layout>default</layout>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>
...
<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-SNAPSHOT</version>
</dependency>

or Gradle:

repositories {
    maven { url "http://adxsnapshots.azurewebsites.net/" }
    ....
}
...
dependencies {
    compile 'com.microsoft.azure:azure:1.0.0-SNAPSHOT'
    ....
}

Client Creation

Creating a service client is simple. Every Azure Resource Manager client provides 4 constructors to use with simple parameters.

ComputeManagementClient client;

// Default environment, no credentials
client = new ComputeManagementClientImpl();

// Custom environment with AzureChinaCloud endpoint
String chinaCloudEndpoint = "https://management.chinacloudapi.cn/";
client = new ComputeManagementClientImpl(chinaCloudEndpoint);

// Default environment with credentials
ApplicationTokenCredentials credentials = new ApplicationTokenCredentials(
        "client-id", "tenant-id", "secret", null);
client = new ComputeManagementClientImpl(credentials);

// Custom environment with credentials
client = new ComputeManagementClientImpl(chinaCloudEndpoint, credentials);

// Fully customized, with HTTP client and Retrofit modifiable
client = new ComputeManagementClientImpl(
        chinaCloudEndpoint,
        credentials,
        new OkHttpClient.Builder(),
        new Retrofit.Builder());

Please see Authentication for more information about creating credentials.

Authentication

Azure SDK for Java does not provide direct authentication to Azure. However, interceptors pluggable into the OkHttp client have been provided for injecting tokens into HTTP requests.

We provide separate libraries for authenticating through Azure Active Directory. They are azure-client-authentication and azure-android-client-authentication, for JDK and Android respectively. They are pluggable into the interceptors we provide in the SDK to feed the tokens.

JDK

In azure-client-authentication, 2 authentication credentials are provided:

UserTokenCredentials

UserTokenCredentials credentials = new UserTokenCredentials(
        "client-id",
        "tenant-id/domain",
        "username",
        "password",
        "client-redirect-uri",
        AzureEnvironment.Azure);

Information about client ID, and client redirect URI are retrieved from your application in the Azure Active Directory.

This scenario is useful for interactive apps running on JDK. However, as of ADAL4j 1.1.2 two-factor-auth has not been supported yet.

ApplicationTokenCredentials

ApplicationTokenCredentials credentials = new ApplicationTokenCredentials(
        "client-id",
        "tenant-id/domain",
        "secret",
        AzureEnvironment.Azure);

Information about client ID, and client redirect URI are retrieved from your application in the Azure Active Directory.

This scenario is useful for most service principal based authentications. For a reference on setting up a service principal from the command line see Authenticating a service principal with Azure Resource Manager or Unattended Authentication. For a more robust explanation of authentication in Azure, see Developer’s guide to auth with Azure Resource Manager API.

Android

In azure-android-client-authentication, only UserTokenCredentials is provided because interactive flow is supported for authentication on Android.

UserTokenCredentials

// Simpler constructor
UserTokenCredentials credentials = new UserTokenCredentials(
        getApplicationContext(),
        "client-id",
        "tenant-id/domain",
        "client-redirect-uri");
        
// Detailed constructor
UserTokenCredentials credentials = new UserTokenCredentials(
        getApplicationContext(),
        "client-id",
        "tenant-id/domain",
        "client-redirect-uri",
        PromptBehavior.Always,
        AzureEnvironment.Azure);

An android Activity object is required for the 1st argument, simply for shared preference access. When authentication is needed, a login window will prompt and ask for credentials. Once the authentication is done, it goes back to the previous activity from which the login window is prompted.

Two factor auth is supported on Android.

Synchronous calls

Once you have your client created, you will have a set of operations available to you. You can access them through

VirtualMachinesOperations vmOps = computeManagementClient.getVirtualMachinesOperations();
AvailabilitySetsOperations asOps = computeManagementClient.getAvailabilitySetsOperations();
// etc

Each operation is a method group containing a set of methods accessing a type of resource.

List<VirtualMachine> vms = vmOps.listAll().getBody();

will list all the VMs in your subscription.

Asynchronous calls

The listAll() call above has an asynchronous version:

vmOps.listAllAsync(new ListOperationCallback<VirtualMachine>() {
    @Override
    public void failure(Throwable t) {
        // handle failure
    }

    @Override
    public void success(final ServiceResponse<List<ResourceGroup>> result) {
        // handle result
    }
});

Please note that by default, the callbacks run on main thread on JDK, and the UI thread on Android. In order to let callbacks run on asynchronous threads, configure the Retrofit.Builder instance with callbackExecutor(Executor executor).