mgmt, improve readme in packages (Azure#17251)

Author: weidongxu-microsoft

sdk/resourcemanager/README.md

@@ -77,6 +77,7 @@ In addition, Azure subscription ID can be configured via environment variable `A
 
 With above configuration, `azure` client can be authenticated by following code:
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L62-L68 -->
 ```java
 AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
 TokenCredential credential = new DefaultAzureCredentialBuilder()
@@ -142,84 +143,84 @@ Services in preview
 
 You can create a virtual machine instance, together with required virtual network and ip address created automatically.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L95-L105 -->
 ```java
 VirtualMachine linuxVM = azure.virtualMachines().define("myLinuxVM")
     .withRegion(Region.US_EAST)
     .withNewResourceGroup(rgName)
     .withNewPrimaryNetwork("10.0.0.0/28")
     .withPrimaryPrivateIPAddressDynamic()
-    .withNewPrimaryPublicIPAddress("mylinuxvm")
-    .withPopularLinuxImage(KnownLinuxVirtualMachineImage.UBUNTU_SERVER_16_04_LTS)
-    .withRootUsername("tirekicker")
-    .withSsh(sshKey)
+    .withoutPrimaryPublicIPAddress()
+    .withPopularLinuxImage(KnownLinuxVirtualMachineImage.UBUNTU_SERVER_18_04_LTS)
+    .withRootUsername("<username>")
+    .withSsh("<ssh-key>")
     .withSize(VirtualMachineSizeTypes.STANDARD_D3_V2)
     .create();
 ```
 
 Update.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L107-L109 -->
 ```java
 linuxVM.update()
-    .withNewDataDisk(20, lun, CachingTypes.READ_WRITE)
+    .withNewDataDisk(10, 0, CachingTypes.READ_WRITE)
     .apply();
 ```
 
 ### Dependency across Azure resources
 
 You can create a function app, together with required storage account and app service plan created on specification.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L115-L135 -->
 ```java
 Creatable<StorageAccount> creatableStorageAccount = azure.storageAccounts()
-    .define(storageAccountName)
+    .define("<storage-account-name>")
     .withRegion(Region.US_EAST)
     .withExistingResourceGroup(rgName)
     .withGeneralPurposeAccountKindV2()
     .withSku(StorageAccountSkuType.STANDARD_LRS);
-
 Creatable<AppServicePlan> creatableAppServicePlan = azure.appServicePlans()
-    .define(appServicePlanName)
+    .define("<app-service-plan-name>")
     .withRegion(Region.US_EAST)
     .withExistingResourceGroup(rgName)
     .withPricingTier(PricingTier.STANDARD_S1)
     .withOperatingSystem(OperatingSystem.LINUX);
-
-FunctionApp linuxFunctionApp = azure.functionApps().define(functionAppName)
+FunctionApp linuxFunctionApp = azure.functionApps().define("<function-app-name>")
     .withRegion(Region.US_EAST)
     .withExistingResourceGroup(rgName)
     .withNewLinuxAppServicePlan(creatableAppServicePlan)
     .withBuiltInImage(FunctionRuntimeStack.JAVA_8)
     .withNewStorageAccount(creatableStorageAccount)
     .withHttpsOnly(true)
-    .withAppSetting("WEBSITE_RUN_FROM_PACKAGE", functionAppPackageUrl)
+    .withAppSetting("WEBSITE_RUN_FROM_PACKAGE", "<function-app-package-url>")
     .create();
 ```
 
 ### Batch Azure resource provisioning
 
 You can batch create and delete managed disk instances.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L141-L152 -->
 ```java
 List<String> diskNames = Arrays.asList("datadisk1", "datadisk2");
-
 List<Creatable<Disk>> creatableDisks = diskNames.stream()
     .map(diskName -> azure.disks()
         .define(diskName)
         .withRegion(Region.US_EAST)
         .withExistingResourceGroup(rgName)
         .withData()
-        .withSizeInGB(1)
+        .withSizeInGB(10)
         .withSku(DiskSkuTypes.STANDARD_LRS))
     .collect(Collectors.toList());
-
 Collection<Disk> disks = azure.disks().create(creatableDisks).values();
-
 azure.disks().deleteByIds(disks.stream().map(Disk::id).collect(Collectors.toList()));
 ```
 
 ### Integration with Azure role-based access control
 
 You can assign Contributor for an Azure resource to a service principal.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L160-L166 -->
 ```java
 String raName = UUID.randomUUID().toString();
 RoleAssignment roleAssignment = azure.accessManagement().roleAssignments()
@@ -234,8 +235,9 @@ RoleAssignment roleAssignment = azure.accessManagement().roleAssignments()
 
 You can create storage account, then blob container, in reactive programming.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L172-L185 -->
 ```java
-azure.storageAccounts().define(storageAccountName)
+azure.storageAccounts().define("<storage-account-name>")
     .withRegion(Region.US_EAST)
     .withNewResourceGroup(rgName)
     .withSku(StorageAccountSkuType.STANDARD_LRS)
@@ -248,28 +250,29 @@ azure.storageAccounts().define(storageAccountName)
         .withPublicAccess(PublicAccess.BLOB)
         .createAsync()
     )
-    ...
+    //...
 ```
 
 You can operate on virtual machines in parallel.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L192-L194 -->
 ```java
 azure.virtualMachines().listByResourceGroupAsync(rgName)
     .flatMap(VirtualMachine::restartAsync)
-    ...
+    //...
 ```
 
 ### Configurable client
 
-You can customize various aspects of the client.
+You can customize various aspects of the client and pipeline.
 
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L206-L210 -->
 ```java
 AzureResourceManager azure = AzureResourceManager
     .configure()
     .withHttpClient(customizedHttpClient)
     .withPolicy(additionalPolicy)
-    .withConfiguration(customizedConfiguration)
-    ...
+    //...
 ```
 
 ### Include single package
@@ -289,9 +292,11 @@ For example, here is sample maven dependency for Compute package.
 [//]: # ({x-version-update-end})
 
 Sample code to create the authenticated client.
+
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L88-L89 -->
 ```java
-ComputeManager client = ComputeManager.authenticate(credential, profile);
-client.virtualMachines().listByResourceGroup(rgName);
+ComputeManager manager = ComputeManager.authenticate(credential, profile);
+manager.virtualMachines().list();
 ```
 
 ## Troubleshooting
@@ -314,6 +319,8 @@ their resolution. The logs produced will capture the flow of an application befo
 locate the root issue. View the [logging][logging] wiki for guidance about enabling logging.
 
 Sample code to enable logging in Azure Management Libraries.
+
+<!-- embedme ./azure-resourcemanager/src/samples/java/com/azure/resourcemanager/ReadmeSamples.java#L76-L80 -->
 ```java
 AzureResourceManager azure = AzureResourceManager
     .configure()

sdk/resourcemanager/azure-resourcemanager-appplatform/README.md

@@ -8,7 +8,8 @@ For documentation on how to use this package, please see [Azure Management Libra
 
 ### Prerequisites
 
-- Java Development Kit (JDK) with version 8 or above
+- [Java Development Kit (JDK)][jdk] with version 8 or above
+- [Azure Subscription][azure_subscription]
 
 ### Adding the package to your product
 
@@ -22,10 +23,46 @@ For documentation on how to use this package, please see [Azure Management Libra
 ```
 [//]: # ({x-version-update-end})
 
+### Include the recommended packages
+
+Azure Management Libraries require a `TokenCredential` implementation for authentication and an `HttpClient` implementation for HTTP client.
+
+[Azure Identity][azure_identity] package and [Azure Core Netty HTTP][azure_core_http_netty] package provide the default implementation.
+
+### Authentication
+
+By default, Azure Active Directory token authentication depends on correct configure of following environment variables.
+
+- `AZURE_CLIENT_ID` for Azure client ID.
+- `AZURE_TENANT_ID` for Azure tenant ID.
+- `AZURE_CLIENT_SECRET` or `AZURE_CLIENT_CERTIFICATE_PATH` for client secret or client certificate.
+
+In addition, Azure subscription ID can be configured via environment variable `AZURE_SUBSCRIPTION_ID`.
+
+With above configuration, `azure` client can be authenticated by following code:
+
+<!-- embedme ./src/samples/java/com/azure/resourcemanager/appplatform/ReadmeSamples.java#L21-L26 -->
+```java
+AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
+TokenCredential credential = new DefaultAzureCredentialBuilder()
+    .authorityHost(profile.getEnvironment().getActiveDirectoryEndpoint())
+    .build();
+AppPlatformManager manager = AppPlatformManager
+    .authenticate(credential, profile);
+```
+
+The sample code assumes global Azure. Please change `AzureEnvironment.AZURE` variable if otherwise.
+
+See [Authentication][authenticate] for more options.
+
 ## Key concepts
 
+See [API design][design] for general introduction on design and key concepts on Azure Management Libraries.
+
 ## Examples
 
+See [Samples][sample] for code snippets and samples.
+
 ## Troubleshooting
 
 ## Next steps
@@ -40,3 +77,12 @@ Azure Projects Contribution Guidelines](https://azure.github.io/guidelines.html)
 1. Commit your changes (`git commit -am 'Add some feature'`)
 1. Push to the branch (`git push origin my-new-feature`)
 1. Create new Pull Request
+
+<!-- LINKS -->
+[jdk]: https://docs.microsoft.com/java/azure/jdk/
+[azure_subscription]: https://azure.microsoft.com/free/
+[azure_identity]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/identity/azure-identity
+[azure_core_http_netty]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core-http-netty
+[authenticate]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/resourcemanager/docs/AUTH.md
+[sample]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/resourcemanager/docs/SAMPLE.md
+[design]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/resourcemanager/docs/DESIGN.md

sdk/resourcemanager/azure-resourcemanager-appplatform/src/samples/java/com/azure/resourcemanager/appplatform/ReadmeSamples.java

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.resourcemanager.appplatform;
+
+import com.azure.core.credential.TokenCredential;
+import com.azure.core.management.AzureEnvironment;
+import com.azure.core.management.profile.AzureProfile;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+
+/**
+ * WARNING: MODIFYING THIS FILE WILL REQUIRE CORRESPONDING UPDATES TO README.md FILE. LINE NUMBERS
+ * ARE USED TO EXTRACT APPROPRIATE CODE SEGMENTS FROM THIS FILE. ADD NEW CODE AT THE BOTTOM TO AVOID CHANGING
+ * LINE NUMBERS OF EXISTING CODE SAMPLES.
+ *
+ * Code samples for the README.md
+ */
+public class ReadmeSamples {
+
+    public void authenticate() {
+        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
+        TokenCredential credential = new DefaultAzureCredentialBuilder()
+            .authorityHost(profile.getEnvironment().getActiveDirectoryEndpoint())
+            .build();
+        AppPlatformManager manager = AppPlatformManager
+            .authenticate(credential, profile);
+    }
+}

sdk/resourcemanager/azure-resourcemanager-appservice/README.md

@@ -8,7 +8,8 @@ For documentation on how to use this package, please see [Azure Management Libra
 
 ### Prerequisites
 
-- Java Development Kit (JDK) with version 8 or above
+- [Java Development Kit (JDK)][jdk] with version 8 or above
+- [Azure Subscription][azure_subscription]
 
 ### Adding the package to your product
 
@@ -22,10 +23,46 @@ For documentation on how to use this package, please see [Azure Management Libra
 ```
 [//]: # ({x-version-update-end})
 
+### Include the recommended packages
+
+Azure Management Libraries require a `TokenCredential` implementation for authentication and an `HttpClient` implementation for HTTP client.
+
+[Azure Identity][azure_identity] package and [Azure Core Netty HTTP][azure_core_http_netty] package provide the default implementation.
+
+### Authentication
+
+By default, Azure Active Directory token authentication depends on correct configure of following environment variables.
+
+- `AZURE_CLIENT_ID` for Azure client ID.
+- `AZURE_TENANT_ID` for Azure tenant ID.
+- `AZURE_CLIENT_SECRET` or `AZURE_CLIENT_CERTIFICATE_PATH` for client secret or client certificate.
+
+In addition, Azure subscription ID can be configured via environment variable `AZURE_SUBSCRIPTION_ID`.
+
+With above configuration, `azure` client can be authenticated by following code:
+
+<!-- embedme ./src/samples/java/com/azure/resourcemanager/appservice/ReadmeSamples.java#L21-L26 -->
+```java
+AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
+TokenCredential credential = new DefaultAzureCredentialBuilder()
+    .authorityHost(profile.getEnvironment().getActiveDirectoryEndpoint())
+    .build();
+AppServiceManager manager = AppServiceManager
+    .authenticate(credential, profile);
+```
+
+The sample code assumes global Azure. Please change `AzureEnvironment.AZURE` variable if otherwise.
+
+See [Authentication][authenticate] for more options.
+
 ## Key concepts
 
+See [API design][design] for general introduction on design and key concepts on Azure Management Libraries.
+
 ## Examples
 
+See [Samples][sample] for code snippets and samples.
+
 ## Troubleshooting
 
 ## Next steps
@@ -40,3 +77,12 @@ Azure Projects Contribution Guidelines](https://azure.github.io/guidelines.html)
 1. Commit your changes (`git commit -am 'Add some feature'`)
 1. Push to the branch (`git push origin my-new-feature`)
 1. Create new Pull Request
+
+<!-- LINKS -->
+[jdk]: https://docs.microsoft.com/java/azure/jdk/
+[azure_subscription]: https://azure.microsoft.com/free/
+[azure_identity]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/identity/azure-identity
+[azure_core_http_netty]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core-http-netty
+[authenticate]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/resourcemanager/docs/AUTH.md
+[sample]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/resourcemanager/docs/SAMPLE.md
+[design]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/resourcemanager/docs/DESIGN.md

sdk/resourcemanager/azure-resourcemanager-appservice/src/samples/java/com/azure/resourcemanager/appservice/ReadmeSamples.java

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.resourcemanager.appservice;
+
+import com.azure.core.credential.TokenCredential;
+import com.azure.core.management.AzureEnvironment;
+import com.azure.core.management.profile.AzureProfile;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+
+/**
+ * WARNING: MODIFYING THIS FILE WILL REQUIRE CORRESPONDING UPDATES TO README.md FILE. LINE NUMBERS
+ * ARE USED TO EXTRACT APPROPRIATE CODE SEGMENTS FROM THIS FILE. ADD NEW CODE AT THE BOTTOM TO AVOID CHANGING
+ * LINE NUMBERS OF EXISTING CODE SAMPLES.
+ *
+ * Code samples for the README.md
+ */
+public class ReadmeSamples {
+
+    public void authenticate() {
+        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
+        TokenCredential credential = new DefaultAzureCredentialBuilder()
+            .authorityHost(profile.getEnvironment().getActiveDirectoryEndpoint())
+            .build();
+        AppServiceManager manager = AppServiceManager
+            .authenticate(credential, profile);
+    }
+}