|
1 | | -## Azure AzureStackManagementClient SDK for JavaScript |
| 1 | +# AzureStackManagement client library for JavaScript |
2 | 2 |
|
3 | | -This package contains an isomorphic SDK (runs both in Node.js and in browsers) for AzureStackManagementClient. |
| 3 | +This package contains an isomorphic SDK (runs both in Node.js and in browsers) for AzureStackManagement client. |
| 4 | + |
| 5 | +Azure Stack |
| 6 | + |
| 7 | +[Source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/azurestack/arm-azurestack) | |
| 8 | +[Package (NPM)](https://www.npmjs.com/package/@azure/arm-azurestack) | |
| 9 | +[API reference documentation](https://docs.microsoft.com/javascript/api/@azure/arm-azurestack?view=azure-node-preview) | |
| 10 | +[Samples](https://github.com/Azure-Samples/azure-samples-js-management) |
| 11 | + |
| 12 | +## Getting started |
4 | 13 |
|
5 | 14 | ### Currently supported environments |
6 | 15 |
|
7 | 16 | - [LTS versions of Node.js](https://nodejs.org/about/releases/) |
8 | | -- Latest versions of Safari, Chrome, Edge, and Firefox. |
| 17 | +- Latest versions of Safari, Chrome, Edge and Firefox. |
9 | 18 |
|
10 | 19 | ### Prerequisites |
11 | 20 |
|
12 | | -You must have an [Azure subscription](https://azure.microsoft.com/free/). |
| 21 | +- An [Azure subscription][azure_sub]. |
13 | 22 |
|
14 | | -### How to install |
| 23 | +### Install the `@azure/arm-azurestack` package |
15 | 24 |
|
16 | | -To use this SDK in your project, you will need to install two packages. |
17 | | -- `@azure/arm-azurestack` that contains the client. |
18 | | -- `@azure/identity` that provides different mechanisms for the client to authenticate your requests using Azure Active Directory. |
| 25 | +Install the AzureStackManagement client library for JavaScript with `npm`: |
19 | 26 |
|
20 | | -Install both packages using the below command: |
21 | 27 | ```bash |
22 | | -npm install --save @azure/arm-azurestack @azure/identity |
| 28 | +npm install @azure/arm-azurestack |
23 | 29 | ``` |
24 | 30 |
|
25 | | -> **Note**: You may have used either `@azure/ms-rest-nodeauth` or `@azure/ms-rest-browserauth` in the past. These packages are in maintenance mode receiving critical bug fixes, but no new features. |
26 | | -If you are on a [Node.js that has LTS status](https://nodejs.org/about/releases/), or are writing a client side browser application, we strongly encourage you to upgrade to `@azure/identity` which uses the latest versions of Azure Active Directory and MSAL APIs and provides more authentication options. |
| 31 | +### Create and authenticate a `AzureStackManagementClient` |
27 | 32 |
|
28 | | -### How to use |
| 33 | +To create a client object to access the AzureStackManagement API, you will need the `endpoint` of your AzureStackManagement resource and a `credential`. The AzureStackManagement client can use Azure Active Directory credentials to authenticate. |
| 34 | +You can find the endpoint for your AzureStackManagement resource in the [Azure Portal][azure_portal]. |
29 | 35 |
|
30 | | -- If you are writing a client side browser application, |
31 | | - - Follow the instructions in the section on Authenticating client side browser applications in [Azure Identity examples](https://aka.ms/azsdk/js/identity/examples) to register your application in the Microsoft identity platform and set the right permissions. |
32 | | - - Copy the client ID and tenant ID from the Overview section of your app registration in Azure portal and use it in the browser sample below. |
33 | | -- If you are writing a server side application, |
34 | | - - [Select a credential from `@azure/identity` based on the authentication method of your choice](https://aka.ms/azsdk/js/identity/examples) |
35 | | - - Complete the set up steps required by the credential if any. |
36 | | - - Use the credential you picked in the place of `DefaultAzureCredential` in the Node.js sample below. |
| 36 | +You can authenticate with Azure Active Directory using a credential from the [@azure/identity][azure_identity] library or [an existing AAD Token](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/samples/AzureIdentityExamples.md#authenticating-with-a-pre-fetched-access-token). |
37 | 37 |
|
38 | | -In the below samples, we pass the credential and the Azure subscription id to instantiate the client. |
39 | | -Once the client is created, explore the operations on it either in your favorite editor or in our [API reference documentation](https://docs.microsoft.com/javascript/api) to get started. |
| 38 | +To use the [DefaultAzureCredential][defaultazurecredential] provider shown below, or other credential providers provided with the Azure SDK, please install the `@azure/identity` package: |
| 39 | + |
| 40 | +```bash |
| 41 | +npm install @azure/identity |
| 42 | +``` |
40 | 43 |
|
41 | | -#### nodejs - Authentication, client creation, and list operations as an example written in JavaScript. |
| 44 | +You will also need to **register a new AAD application and grant access to AzureStackManagement** by assigning the suitable role to your service principal (note: roles such as `"Owner"` will not grant the necessary permissions). |
| 45 | +Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`. |
42 | 46 |
|
43 | | -##### Sample code |
| 47 | +For more information about how to create an Azure AD Application check out [this guide](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). |
44 | 48 |
|
45 | 49 | ```javascript |
46 | | -const { DefaultAzureCredential } = require("@azure/identity"); |
47 | 50 | const { AzureStackManagementClient } = require("@azure/arm-azurestack"); |
48 | | -const subscriptionId = process.env["AZURE_SUBSCRIPTION_ID"]; |
49 | | - |
50 | | -// Use `DefaultAzureCredential` or any other credential of your choice based on https://aka.ms/azsdk/js/identity/examples |
51 | | -// Please note that you can also use credentials from the `@azure/ms-rest-nodeauth` package instead. |
52 | | -const creds = new DefaultAzureCredential(); |
53 | | -const client = new AzureStackManagementClient(creds, subscriptionId); |
54 | | - |
55 | | -client.operations.list().then((result) => { |
56 | | - console.log("The result is:"); |
57 | | - console.log(result); |
58 | | -}).catch((err) => { |
59 | | - console.log("An error occurred:"); |
60 | | - console.error(err); |
61 | | -}); |
| 51 | +const { DefaultAzureCredential } = require("@azure/identity"); |
| 52 | +const subscriptionId = "00000000-0000-0000-0000-000000000000"; |
| 53 | +const client = new AzureStackManagementClient(new DefaultAzureCredential(), subscriptionId); |
62 | 54 | ``` |
63 | 55 |
|
64 | | -#### browser - Authentication, client creation, and list operations as an example written in JavaScript. |
65 | | - |
66 | | -In browser applications, we recommend using the `InteractiveBrowserCredential` that interactively authenticates using the default system browser. |
67 | | - - See [Single-page application: App registration guide](https://docs.microsoft.com/azure/active-directory/develop/scenario-spa-app-registration) to configure your app registration for the browser. |
68 | | - - Note down the client Id from the previous step and use it in the browser sample below. |
69 | | - |
70 | | -##### Sample code |
71 | | - |
72 | | -- index.html |
73 | | - |
74 | | -```html |
75 | | -<!DOCTYPE html> |
76 | | -<html lang="en"> |
77 | | - <head> |
78 | | - <title>@azure/arm-azurestack sample</title> |
79 | | - <script src="node_modules/@azure/ms-rest-azure-js/dist/msRestAzure.js"></script> |
80 | | - <script src="node_modules/@azure/identity/dist/index.js"></script> |
81 | | - <script src="node_modules/@azure/arm-azurestack/dist/arm-azurestack.js"></script> |
82 | | - <script type="text/javascript"> |
83 | | - const subscriptionId = "<Subscription_Id>"; |
84 | | - // Create credentials using the `@azure/identity` package. |
85 | | - // Please note that you can also use credentials from the `@azure/ms-rest-browserauth` package instead. |
86 | | - const credential = new InteractiveBrowserCredential( |
87 | | - { |
88 | | - clientId: "<client id for your Azure AD app>", |
89 | | - tenantId: "<optional tenant for your organization>" |
90 | | - }); |
91 | | - const client = new Azure.ArmAzurestack.AzureStackManagementClient(creds, subscriptionId); |
92 | | - client.operations.list().then((result) => { |
93 | | - console.log("The result is:"); |
94 | | - console.log(result); |
95 | | - }).catch((err) => { |
96 | | - console.log("An error occurred:"); |
97 | | - console.error(err); |
98 | | - }); |
99 | | - </script> |
100 | | - </head> |
101 | | - <body></body> |
102 | | -</html> |
| 56 | + |
| 57 | +### JavaScript Bundle |
| 58 | +To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our [bundling documentation](https://aka.ms/AzureSDKBundling). |
| 59 | + |
| 60 | +## Key concepts |
| 61 | + |
| 62 | +### AzureStackManagementClient |
| 63 | + |
| 64 | +`AzureStackManagementClient` is the primary interface for developers using the AzureStackManagement client library. Explore the methods on this client object to understand the different features of the AzureStackManagement service that you can access. |
| 65 | + |
| 66 | +## Troubleshooting |
| 67 | + |
| 68 | +### Logging |
| 69 | + |
| 70 | +Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`: |
| 71 | + |
| 72 | +```javascript |
| 73 | +const { setLogLevel } = require("@azure/logger"); |
| 74 | +setLogLevel("info"); |
103 | 75 | ``` |
104 | 76 |
|
| 77 | +For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger). |
| 78 | + |
| 79 | +## Next steps |
| 80 | + |
| 81 | +Please take a look at the [samples](https://github.com/Azure-Samples/azure-samples-js-management) directory for detailed examples on how to use this library. |
| 82 | + |
| 83 | +## Contributing |
| 84 | + |
| 85 | +If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code. |
| 86 | + |
105 | 87 | ## Related projects |
106 | 88 |
|
107 | | -- [Microsoft Azure SDK for Javascript](https://github.com/Azure/azure-sdk-for-js) |
| 89 | +- [Microsoft Azure SDK for JavaScript](https://github.com/Azure/azure-sdk-for-js) |
| 90 | + |
| 91 | + |
108 | 92 |
|
109 | | - |
| 93 | +[azure_cli]: https://docs.microsoft.com/cli/azure |
| 94 | +[azure_sub]: https://azure.microsoft.com/free/ |
| 95 | +[azure_sub]: https://azure.microsoft.com/free/ |
| 96 | +[azure_portal]: https://portal.azure.com |
| 97 | +[azure_identity]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity |
| 98 | +[defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential |
0 commit comments