Azure · sarangan12 · Aug 15, 2022 · Aug 12, 2022 · Aug 12, 2022 · Aug 12, 2022
@@ -2,7 +2,8 @@
 
 ## 11.3.0-beta.8 (unreleased)
 
-Added `core-http-compat` dependency
+- Added `core-http-compat` dependency
+- Enabled national cloud support for Azure Search SDK. Please refer [#22887](https://github.com/Azure/azure-sdk-for-js/pull/22887) for further details.
 
 ## 11.3.0-beta.7 (2022-03-08)
 

@@ -20,6 +20,7 @@ Use the @azure/search-documents client library to:
 - Optimize results through scoring profiles to factor in business logic or freshness.
 
 Key links:
+
 - [Source code](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/search/search-documents/)
 - [Package (NPM)](https://www.npmjs.com/package/@azure/search-documents)
 - [API reference documentation](https://docs.microsoft.com/javascript/api/@azure/search-documents)
@@ -67,9 +68,9 @@ az search admin-key show --resource-group <your-resource-group-name> --service-n
 
 Alternatively, you can get the endpoint and Admin Key from the resource information in the [Azure Portal][azure_portal].
 
-There are two types of keys used to access your search service: **admin** *(read-write)* and **query** *(read-only)* keys.  Restricting access and operations in client apps is essential to safeguarding the search assets on your service.  Always use a query key rather than an admin key for any query originating from a client app.
+There are two types of keys used to access your search service: **admin** _(read-write)_ and **query** _(read-only)_ keys. Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Always use a query key rather than an admin key for any query originating from a client app.
 
-*Note: The example Azure CLI snippet above retrieves an admin key so it's easier to get started exploring APIs, but it should be managed carefully.*
+_Note: The example Azure CLI snippet above retrieves an admin key so it's easier to get started exploring APIs, but it should be managed carefully._
 
 Once you have an api-key, you can use it as follows:
 
@@ -95,25 +96,63 @@ const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("
 const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
 ```
 
+### Authenticate in a National Cloud
+
+To authenticate in a [National Cloud](https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud), you will need to make the following additions to your client configuration:
+
+- Set the `Audience` in `SearchClientOptions`
+
+```js
+const {
+  SearchClient,
+  SearchIndexClient,
+  SearchIndexerClient,
+  AzureKeyCredential,
+  KnownSearchAudience,
+} = require("@azure/search-documents");
+
+// To query and manipulate documents
+const searchClient = new SearchClient(
+  "<endpoint>",
+  "<indexName>",
+  new AzureKeyCredential("<apiKey>"),
+  {
+    audience: KnownSearchAudience.AzureChina,
+  }
+);
+
+// To manage indexes and synonymmaps
+const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
+  audience: KnownSearchAudience.AzureChina,
+});
+
+// To manage indexers, datasources and skillsets
+const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
+  audience: KnownSearchAudience.AzureChina,
+});
+```
+
 ## Key concepts
-An Azure Cognitive Search service contains one or more indexes that provide persistent storage of searchable data in the form of JSON documents.  _(If you're brand new to search, you can make a very rough analogy between indexes and database tables.)_  The @azure/search-documents client library
+
+An Azure Cognitive Search service contains one or more indexes that provide persistent storage of searchable data in the form of JSON documents. _(If you're brand new to search, you can make a very rough analogy between indexes and database tables.)_ The @azure/search-documents client library
 exposes operations on these resources through three main client types.
 
-* `SearchClient` helps with:
-  * [Searching](https://docs.microsoft.com/azure/search/search-lucene-query-architecture) your indexed documents using [rich queries](https://docs.microsoft.com/azure/search/search-query-overview) and [powerful data shaping](https://docs.microsoft.com/azure/search/search-filters)
-  * [Autocompleting](https://docs.microsoft.com/rest/api/searchservice/autocomplete) partially typed search terms based on documents in the index
-  * [Suggesting](https://docs.microsoft.com/rest/api/searchservice/suggestions) the most likely matching text in documents as a user types
-  * [Adding, Updating or Deleting Documents](https://docs.microsoft.com/rest/api/searchservice/addupdate-or-delete-documents) documents from an index
-* `SearchIndexClient` allows you to:
-  * [Create, delete, update, or configure a search index](https://docs.microsoft.com/rest/api/searchservice/index-operations)
-  * [Declare custom synonym maps to expand or rewrite queries](https://docs.microsoft.com/rest/api/searchservice/synonym-map-operations)
-* `SearchIndexerClient` allows you to:
-  * [Start indexers to automatically crawl data sources](https://docs.microsoft.com/rest/api/searchservice/indexer-operations)
-  * [Define AI powered Skillsets to transform and enrich your data](https://docs.microsoft.com/rest/api/searchservice/skillset-operations)
+- `SearchClient` helps with:
+  - [Searching](https://docs.microsoft.com/azure/search/search-lucene-query-architecture) your indexed documents using [rich queries](https://docs.microsoft.com/azure/search/search-query-overview) and [powerful data shaping](https://docs.microsoft.com/azure/search/search-filters)
+  - [Autocompleting](https://docs.microsoft.com/rest/api/searchservice/autocomplete) partially typed search terms based on documents in the index
+  - [Suggesting](https://docs.microsoft.com/rest/api/searchservice/suggestions) the most likely matching text in documents as a user types
+  - [Adding, Updating or Deleting Documents](https://docs.microsoft.com/rest/api/searchservice/addupdate-or-delete-documents) documents from an index
+- `SearchIndexClient` allows you to:
+  - [Create, delete, update, or configure a search index](https://docs.microsoft.com/rest/api/searchservice/index-operations)
+  - [Declare custom synonym maps to expand or rewrite queries](https://docs.microsoft.com/rest/api/searchservice/synonym-map-operations)
+- `SearchIndexerClient` allows you to:
+  - [Start indexers to automatically crawl data sources](https://docs.microsoft.com/rest/api/searchservice/indexer-operations)
+  - [Define AI powered Skillsets to transform and enrich your data](https://docs.microsoft.com/rest/api/searchservice/skillset-operations)
 
 **Note**: These clients cannot function in the browser because the APIs it calls do not have support for Cross-Origin Resource Sharing (CORS).
 
 ## TypeScript/JavaScript specific concepts
+
 ### Documents
 
 An item stored inside a search index. The shape of this document is described in the index using `Field`s. Each Field has a name, a datatype, and additional metadata such as if it is searchable or filterable.
@@ -136,13 +175,13 @@ Typically you will only wish to [show a subset of search results](https://docs.m
 
 The following examples demonstrate the basics - please [check out our samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/search/search-documents/samples) for much more.
 
-* [Creating an index](#create-an-index)
-* [Retrieving a specific document from your index](#retrieve-a-specific-document-from-an-index)
-* [Adding documents to your index](#adding-documents-into-an-index)
-* [Perform a search on documents](#perform-a-search-on-documents)
-  * [Querying with TypeScript](#querying-with-typescript)
-  * [Querying with OData filters](#querying-with-odata-filters)
-  * [Querying with facets](#querying-with-facets)
+- [Creating an index](#create-an-index)
+- [Retrieving a specific document from your index](#retrieve-a-specific-document-from-an-index)
+- [Adding documents to your index](#adding-documents-into-an-index)
+- [Perform a search on documents](#perform-a-search-on-documents)
+  - [Querying with TypeScript](#querying-with-typescript)
+  - [Querying with OData filters](#querying-with-odata-filters)
+  - [Querying with facets](#querying-with-facets)
 
 ### Create an Index
 
@@ -204,11 +243,7 @@ A specific document can be retrieved by its primary key value:
 ```js
 const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
 
-const client = new SearchClient(
-  "<endpoint>",
-  "<indexName>",
-  new AzureKeyCredential("<apiKey>")
-);
+const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
 
 async function main() {
   const result = await client.getDocument("1234");
@@ -225,11 +260,7 @@ You can upload multiple documents into index inside a batch:
 ```js
 const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
 
-const client = new SearchClient(
-  "<endpoint>",
-  "<indexName>",
-  new AzureKeyCredential("<apiKey>")
-);
+const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
 
 async function main() {
   const uploadResult = await client.uploadDocuments([
@@ -253,11 +284,7 @@ To list all results of a particular query, you can use `search` with a search st
 ```js
 const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
 
-const client = new SearchClient(
-  "<endpoint>",
-  "<indexName>",
-  new AzureKeyCredential("<apiKey>")
-);
+const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
 
 async function main() {
   const searchResults = await client.search("wifi -luxury");
@@ -274,11 +301,7 @@ For a more advanced search that uses [Lucene syntax](https://docs.microsoft.com/
 ```js
 const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
 
-const client = new SearchClient(
-  "<endpoint>",
-  "<indexName>",
-  new AzureKeyCredential("<apiKey>")
-);
+const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
 
 async function main() {
   const searchResults = await client.search('Category:budget AND "recently renovated"^3', {
@@ -340,11 +363,7 @@ Using the `filter` query parameter allows you to query an index using the syntax
 ```js
 const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");
 
-const client = new SearchClient(
-  "<endpoint>",
-  "<indexName>",
-  new AzureKeyCredential("<apiKey>")
-);
+const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
 
 async function main() {
   const baseRateMax = 200;
@@ -371,11 +390,7 @@ main();
 ```js
 const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");
 
-const client = new SearchClient(
-  "<endpoint>",
-  "<indexName>",
-  new AzureKeyCredential("<apiKey>")
-);
+const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));
 
 async function main() {
   const searchResults = await client.search("WiFi", {
@@ -417,15 +432,16 @@ setLogLevel("info");
 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).
 
 ## Next steps
-* [Go further with search-documents and our samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/search/search-documents/samples)
-* [Watch a demo or deep dive video](https://azure.microsoft.com/resources/videos/index/?services=search)
-* [Read more about the Azure Cognitive Search service](https://docs.microsoft.com/azure/search/search-what-is-azure-search)
+
+- [Go further with search-documents and our samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/search/search-documents/samples)
+- [Watch a demo or deep dive video](https://azure.microsoft.com/resources/videos/index/?services=search)
+- [Read more about the Azure Cognitive Search service](https://docs.microsoft.com/azure/search/search-what-is-azure-search)
 
 ## Contributing
 
 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.
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
 
 This project has adopted the [Microsoft Open Source Code of Conduct][coc].For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
 

@@ -1287,6 +1287,13 @@ export enum KnownRegexFlags {
     UnixLines = "UNIX_LINES"
 }
 
+// @public
+export enum KnownSearchAudience {
+    AzureChina = "https://search.azure.cn",
+    AzureGovernment = "https://search.azure.us",
+    AzurePublicCloud = "https://search.azure.com"
+}
+
 // @public
 export enum KnownSearchIndexerDataSourceType {
     AdlsGen2 = "adlsgen2",
@@ -1863,6 +1870,7 @@ export class SearchClient<T> implements IndexDocumentsClient<T> {
 export interface SearchClientOptions extends ExtendedCommonClientOptions {
     // @deprecated
     apiVersion?: string;
+    audience?: string;
     serviceVersion?: string;
 }
 
@@ -1949,6 +1957,7 @@ export class SearchIndexClient {
 export interface SearchIndexClientOptions extends ExtendedCommonClientOptions {
     // @deprecated
     apiVersion?: string;
+    audience?: string;
     serviceVersion?: string;
 }
 
@@ -2011,6 +2020,7 @@ export class SearchIndexerClient {
 export interface SearchIndexerClientOptions extends ExtendedCommonClientOptions {
     // @deprecated
     apiVersion?: string;
+    audience?: string;
     serviceVersion?: string;
 }
 

@@ -342,3 +342,4 @@ export {
 } from "./generated/service/models";
 export { AzureKeyCredential } from "@azure/core-auth";
 export { createSynonymMapFromFile } from "./synonymMapHelper";
+export { KnownSearchAudience } from "./searchAudience";
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Known values for Search Audience
+ */
+export enum KnownSearchAudience {
+  /**
+   * Audience for Azure China
+   */
+  AzureChina = "https://search.azure.cn",
+  /**
+   * Audience for Azure Government
+   */
+  AzureGovernment = "https://search.azure.us",
+  /**
+   * Audience for Azure Public
+   */
+  AzurePublicCloud = "https://search.azure.com",
+}
@@ -43,6 +43,7 @@ import { encode, decode } from "./base64";
 import * as utils from "./serviceUtils";
 import { IndexDocumentsClient } from "./searchIndexingBufferedSender";
 import { ExtendedCommonClientOptions } from "@azure/core-http-compat";
+import { KnownSearchAudience } from "./searchAudience";
 
 /**
  * Client options used to configure Cognitive Search API requests.
@@ -58,6 +59,13 @@ export interface SearchClientOptions extends ExtendedCommonClientOptions {
    * The service version to use when communicating with the service.
    */
   serviceVersion?: string;
+
+  /**
+   * The Audience to use for authentication with Azure Active Directory (AAD). The
+   * audience is not considered when using a shared key.
+   * {@link KnownSearchAudience} can be used interchangeably with audience
+   */
+  audience?: string;
 }
 
 /**
@@ -175,8 +183,12 @@ export class SearchClient<T> implements IndexDocumentsClient<T> {
     );
 
     if (isTokenCredential(credential)) {
+      const scope: string = options.audience
+        ? `${options.audience}/.default`
+        : `${KnownSearchAudience.AzurePublicCloud}/.default`;
+
       this.client.pipeline.addPolicy(
-        bearerTokenAuthenticationPolicy({ credential, scopes: utils.DEFAULT_SEARCH_SCOPE })
+        bearerTokenAuthenticationPolicy({ credential, scopes: scope })
       );
     } else {
       this.client.pipeline.addPolicy(createSearchApiKeyCredentialPolicy(credential));

@@ -44,6 +44,7 @@ import { createSpan } from "./tracing";
 import { createOdataMetadataPolicy } from "./odataMetadataPolicy";
 import { SearchClient, SearchClientOptions as GetSearchClientOptions } from "./searchClient";
 import { ExtendedCommonClientOptions } from "@azure/core-http-compat";
+import { KnownSearchAudience } from "./searchAudience";
 
 /**
  * Client options used to configure Cognitive Search API requests.
@@ -59,6 +60,13 @@ export interface SearchIndexClientOptions extends ExtendedCommonClientOptions {
    * The service version to use when communicating with the service.
    */
   serviceVersion?: string;
+
+  /**
+   * The Audience to use for authentication with Azure Active Directory (AAD). The
+   * audience is not considered when using a shared key.
+   * {@link KnownSearchAudience} can be used interchangeably with audience
+   */
+  audience?: string;
 }
 
 /**
@@ -175,8 +183,12 @@ export class SearchIndexClient {
     );
 
     if (isTokenCredential(credential)) {
+      const scope: string = options.audience
+        ? `${options.audience}/.default`
+        : `${KnownSearchAudience.AzurePublicCloud}/.default`;
+
       this.client.pipeline.addPolicy(
-        bearerTokenAuthenticationPolicy({ credential, scopes: utils.DEFAULT_SEARCH_SCOPE })
+        bearerTokenAuthenticationPolicy({ credential, scopes: scope })
       );
     } else {
       this.client.pipeline.addPolicy(createSearchApiKeyCredentialPolicy(credential));

@@ -38,6 +38,7 @@ import * as utils from "./serviceUtils";
 import { createSpan } from "./tracing";
 import { createOdataMetadataPolicy } from "./odataMetadataPolicy";
 import { ExtendedCommonClientOptions } from "@azure/core-http-compat";
+import { KnownSearchAudience } from "./searchAudience";
 
 /**
  * Client options used to configure Cognitive Search API requests.
@@ -53,6 +54,13 @@ export interface SearchIndexerClientOptions extends ExtendedCommonClientOptions
    * The service version to use when communicating with the service.
    */
   serviceVersion?: string;
+
+  /**
+   * The Audience to use for authentication with Azure Active Directory (AAD). The
+   * audience is not considered when using a shared key.
+   * {@link KnownSearchAudience} can be used interchangeably with audience
+   */
+  audience?: string;
 }
 
 /**
@@ -157,8 +165,12 @@ export class SearchIndexerClient {
     );
 
     if (isTokenCredential(credential)) {
+      const scope: string = options.audience
+        ? `${options.audience}/.default`
+        : `${KnownSearchAudience.AzurePublicCloud}/.default`;
+
       this.client.pipeline.addPolicy(
-        bearerTokenAuthenticationPolicy({ credential, scopes: utils.DEFAULT_SEARCH_SCOPE })
+        bearerTokenAuthenticationPolicy({ credential, scopes: scope })
       );
     } else {
       this.client.pipeline.addPolicy(createSearchApiKeyCredentialPolicy(credential));