diff --git a/sdk/cognitiveservices/cognitiveservices-computervision/README.md b/sdk/cognitiveservices/cognitiveservices-computervision/README.md index e4067518d8f2..089de54b09cc 100644 --- a/sdk/cognitiveservices/cognitiveservices-computervision/README.md +++ b/sdk/cognitiveservices/cognitiveservices-computervision/README.md @@ -1,64 +1,68 @@ ## An isomorphic javascript sdk for - ComputerVisionClient -This package contains an isomorphic SDK for ComputerVisionClient. +This package contains an isomorphic SDK (runs both in node.js and in browsers) for ComputerVisionClient. ### Currently supported environments -- Node.js version 6.x.x or higher +- Node.js version 8.x.x or higher - Browser JavaScript -### How to Install +### Prerequisites +You must have an [Azure subscription](https://azure.microsoft.com/free/). + +### How to install + +To use this SDK in your project, you will need to install two packages. +- `@azure/cognitiveservices-computervision` that contains the client. +- `@azure/identity` that provides different mechanisms for the client to authenticate your requests using Azure Active Directory. + +Install both packages using the below command: ```bash -npm install @azure/cognitiveservices-computervision +npm install --save @azure/cognitiveservices-computervision @azure/identity ``` +> **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. +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. ### How to use -#### nodejs - Authentication, client creation and listModels as an example written in TypeScript. - -##### Install @azure/ms-rest-azure-js +- If you are writing a client side browser application, + - 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. + - 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. +- If you are writing a server side application, + - [Select a credential from `@azure/identity` based on the authentication method of your choice](https://aka.ms/azsdk/js/identity/examples) + - Complete the set up steps required by the credential if any. + - Use the credential you picked in the place of `DefaultAzureCredential` in the Node.js sample below. -```bash -npm install @azure/ms-rest-azure-js -``` +In the below samples, we pass the credential and the Azure subscription id to instantiate the client. +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. +#### nodejs - Authentication, client creation, and listModels as an example written in JavaScript. ##### Sample code -The following sample describes a given image using Computer Vision. To know more, refer to the [Azure Documentation on Computer Vision](https://docs.microsoft.com/azure/cognitive-services/computer-vision/home) ```javascript +const { DefaultAzureCredential } = require("@azure/identity"); const { ComputerVisionClient } = require("@azure/cognitiveservices-computervision"); -const { CognitiveServicesCredentials } = require("@azure/ms-rest-azure-js"); - -async function main() { - const computerVisionKey = process.env["computerVisionKey"] || ""; - const computerVisionEndPoint = - process.env["computerVisionEndPoint"] || ""; - const cognitiveServiceCredentials = new CognitiveServicesCredentials(computerVisionKey); - const client = new ComputerVisionClient(cognitiveServiceCredentials, computerVisionEndPoint); - - const url = - "https://docs.microsoft.com/azure/includes/media/shared-image-galleries/shared-image-gallery.png"; - const options = { - maxCandidates: 5, - language: "en" - }; - client - .describeImage(url, options) - .then((result) => { - console.log("The result is:"); - console.log(result); - }) - .catch((err) => { - console.log("An error occurred:"); - console.error(err); - }); -} - -main(); +const subscriptionId = process.env["AZURE_SUBSCRIPTION_ID"]; + +// Use `DefaultAzureCredential` or any other credential of your choice based on https://aka.ms/azsdk/js/identity/examples +// Please note that you can also use credentials from the `@azure/ms-rest-nodeauth` package instead. +const creds = new DefaultAzureCredential(); +const client = new ComputerVisionClient(creds, subscriptionId); +client.listModels().then((result) => { + console.log("The result is:"); + console.log(result); +}).catch((err) => { + console.log("An error occurred:"); + console.error(err); +}); ``` -#### browser - Authentication, client creation and listModels as an example written in JavaScript. +#### browser - Authentication, client creation, and listModels as an example written in JavaScript. + +In browser applications, we recommend using the `InteractiveBrowserCredential` that interactively authenticates using the default system browser. + - 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. + - Note down the client Id from the previous step and use it in the browser sample below. ##### Sample code @@ -69,38 +73,24 @@ main(); @azure/cognitiveservices-computervision sample - @@ -111,4 +101,4 @@ main(); - [Microsoft Azure SDK for Javascript](https://github.com/Azure/azure-sdk-for-js) -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fcognitiveservices%2Fcognitiveservices-computervision%2FREADME.png) +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js/sdk/cognitiveservices/cognitiveservices-computervision/README.png) diff --git a/sdk/cognitiveservices/cognitiveservices-computervision/package.json b/sdk/cognitiveservices/cognitiveservices-computervision/package.json index 10d8b4b31bed..f4e5f076a2b1 100644 --- a/sdk/cognitiveservices/cognitiveservices-computervision/package.json +++ b/sdk/cognitiveservices/cognitiveservices-computervision/package.json @@ -4,7 +4,8 @@ "description": "ComputerVisionClient Library with typescript type definitions for node.js and browser.", "version": "8.1.0", "dependencies": { - "@azure/ms-rest-js": "^2.0.4", + "@azure/ms-rest-js": "^2.2.0", + "@azure/core-auth": "^1.1.4", "tslib": "^1.10.0" }, "keywords": [ @@ -19,7 +20,7 @@ "module": "./esm/computerVisionClient.js", "types": "./esm/computerVisionClient.d.ts", "devDependencies": { - "typescript": "^3.5.3", + "typescript": "^3.6.0", "rollup": "^1.18.0", "rollup-plugin-node-resolve": "^5.2.0", "rollup-plugin-sourcemaps": "^0.4.2", diff --git a/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClient.ts b/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClient.ts index 92547bee818d..faa21f95c91d 100644 --- a/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClient.ts +++ b/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClient.ts @@ -18,9 +18,14 @@ class ComputerVisionClient extends ComputerVisionClientContext { * Initializes a new instance of the ComputerVisionClient class. * @param endpoint Supported Cognitive Services endpoints. * @param credentials Subscription credentials which uniquely identify client subscription. + * Credentials implementing the TokenCredential interface from the @azure/identity package are + * recommended. For more information about these credentials, see + * {@link https://www.npmjs.com/package/@azure/identity}. Credentials implementing the + * ServiceClientCredentials interface from the older packages @azure/ms-rest-nodeauth and + * @azure/ms-rest-browserauth are also supported. * @param [options] The parameter options */ - constructor(credentials: msRest.ServiceClientCredentials, endpoint: string, options?: msRest.ServiceClientOptions) { + constructor(credentials: msRest.ServiceClientCredentials | TokenCredential, endpoint: string, options?: msRest.ServiceClientOptions) { super(credentials, endpoint, options); } diff --git a/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClientContext.ts b/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClientContext.ts index 2cf297efbd25..7e14624ded32 100644 --- a/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClientContext.ts +++ b/sdk/cognitiveservices/cognitiveservices-computervision/src/computerVisionClientContext.ts @@ -14,15 +14,20 @@ const packageVersion = "8.1.0"; export class ComputerVisionClientContext extends msRest.ServiceClient { endpoint: string; - credentials: msRest.ServiceClientCredentials; + credentials: msRest.ServiceClientCredentials | TokenCredential; /** * Initializes a new instance of the ComputerVisionClientContext class. * @param endpoint Supported Cognitive Services endpoints. * @param credentials Subscription credentials which uniquely identify client subscription. + * Credentials implementing the TokenCredential interface from the @azure/identity package are + * recommended. For more information about these credentials, see + * {@link https://www.npmjs.com/package/@azure/identity}. Credentials implementing the + * ServiceClientCredentials interface from the older packages @azure/ms-rest-nodeauth and + * @azure/ms-rest-browserauth are also supported. * @param [options] The parameter options */ - constructor(credentials: msRest.ServiceClientCredentials, endpoint: string, options?: msRest.ServiceClientOptions) { + constructor(credentials: msRest.ServiceClientCredentials | TokenCredential, endpoint: string, options?: msRest.ServiceClientOptions) { if (endpoint == undefined) { throw new Error("'endpoint' cannot be null."); }