- <DisplayName>Use email API to send the code the the user</DisplayName>

- <DisplayName>Use SendGrid's email API to send the code the the user</DisplayName>

-1. In your your `ContosoCustomPolicy.XML` file, locate the `UserInformationCollector` self-asserted technical profile, add *reenterPassword* claim as an output claim by using the following code:

- 

-| AuthenticationContextReferenceClaimPattern | No | Controls the `acr` claim value.<ul><li>None - Azure AD B2C doesn't issue the acr claim</li><li>PolicyId - the `acr` claim contains the policy name</li></ul>The options for setting this value are TFP (trust framework policy) and ACR (authentication context reference). It is recommended setting this value to TFP, to set the value, ensure the `<Item>` with the `Key="AuthenticationContextReferenceClaimPattern"` exists and the value is `None`. In your relying party policy, add `<OutputClaims>` item, add this element `<OutputClaim ClaimTypeReferenceId="trustFrameworkPolicy" Required="true" DefaultValue="{policy}" />`. Also make sure your policy contains the claim type `<ClaimType Id="trustFrameworkPolicy"> <DisplayName>trustFrameworkPolicy</DisplayName> <DataType>string</DataType> </ClaimType>` |

- <DisplayName>Use SendGrid's email API to send the code the the user</DisplayName>

-For a local identity, the **passwordProfile** attribute is required, and contains the user's password. The `forceChangePasswordNextSignIn` attribute indicates whether a user must reset the password at the next sign-in. To handle a forced password reset, us the the instructions in [set up forced password reset flow](force-password-reset.md).

-Learn more about [Subscription - BlobReservedCapacity ((Preview) Consider Blob storage reserved instances to save on Blob v2 and and Data Lake storage Gen2 costs)](https://aka.ms/rirecommendations).

-> * If you are assigned as an *Owner* and *LUIS Owner* you will be be shown as *LUIS Owner* in LUIS portal.

-If your device is a local desktop machine or Azure GPU VM (with remote desktop enabled), then then you can switch to `.debug` version of any operation and visualize the output.

-> Images smaller than than 256 pixels will be accepted but upscaled.

- > Custom neural models models are only available in a few regions. If you plan on training a neural model, please select or create a resource in one of [these supported regions](../concept-custom-neural.md#supported-regions).

-> If you are assigned as an *Owner* and *Language Owner* you will be be shown as *Cognitive Services Language Owner* in Language studio portal.

-The matrix compares the the expected labels with the ones predicted by the model.

-^\* Only customers who have been approved for modified content filtering have full content filtering control, including configuring content filters at severity level high only or turning content filters off. Apply for modified content filters via this form: [Azure OpenAI Limited Access Review: Modified Content Filters and Abuse Monitoring (microsoft.com)](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xURE01NDY1OUhBRzQ3MkQxMUhZSE1ZUlJKTiQlQCN0PWcu)

-The maximum length of input text for our embedding models is 2048 tokens (equivalent to around 2-3 pages of text). You should verify that your inputs don't exceed this limit before making a request.

-### Choose the best model for your task

-For the search models, you can obtain embeddings in two ways. The `<search_model>-doc` model is used for longer pieces of text (to be searched over) and the `<search_model>-query` model is used for shorter pieces of text, typically queries or class labels in zero shot classification. You can read more about all of the Embeddings models in our [Models](../concepts/models.md) guide.

-### Replace newlines with a single space

-Unless you're embedding code, we suggest replacing newlines (\n) in your input with a single space, as we have observed inferior results when newlines are present.

-1. In this new knowledge base, open the **Settings** tab and and under _Import knowledge base_ select one of the following options: **QnAs**, **Synonyms**, or **Knowledge Base Replica**.

- "contentUrl": "<Link to to download log file>"

-description: This article shows you how to to Azure Kubernetes Service (AKS).

-In this article, you'll learn how to migrate your Azure Kubernetes Service (AKS) cluster from HTTP application routing feature to the [application routing add-on](./app-routing.md). The HTTP application routing add-on has been retired and won't work on any cluster Kubernetes version currently in support, so we recommend migrating as soon as possible to maintain a supported configuration.

-## Update your cluster's add-ons, ingresses, and IP usage

-2. Update your ingresses, setting `ingressClassName` to `webapprouting.kubernetes.azure.com`. Remove the `kubernetes.io/ingress.class` annotation. You'll also need to update the host to one that you own, as the application routing add-on doesn't have a managed cluster DNS zone. If you don't have a DNS zone, follow instructions to [create][app-routing-dns-create] and [configure][app-routing-dns-configure] one.

- After you've properly updated, the same configuration will look like the following:

-3. Update the ingress controller's IP (such as in DNS records) with the new IP address. You can find the new IP by using `kubectl get`. For example:

-1. After the HTTP application routing add-on is disabled, some related Kubernetes resources may remain in your cluster. These resources include *configmaps* and *secrets* that are created in the *kube-system* namespace. To maintain a clean cluster, you may want to remove these resources. Look for *addon-http-application-routing* resources using the following [`kubectl get`][kubectl-get] commands:

-After migrating to the application routing add-on, learn how to [monitor ingress controller metrics with Prometheus and Grafana](./app-routing-nginx-prometheus.md).

-[ingress-https]: ./ingress-tls.md

-[app-routing-dns-create]: ./app-routing.md?tabs=without-osm#create-an-azure-dns-zone

-[app-routing-dns-configure]: ./app-routing.md?tabs=without-osm#configure-the-add-on-to-use-azure-dns-to-manage-dns-zones

-[dns-pricing]: https://azure.microsoft.com/pricing/details/dns/

-# Managed nginx ingress with the application routing add-on (preview)

-The application routing add-on configures an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) in your Azure Kubernetes Service (AKS) cluster with SSL termination through certificates stored in Azure Key Vault. When you deploy ingresses, the add-on creates publicly accessible DNS names for endpoints on an Azure DNS zone.

-## Application routing add-on with nginx overview

-The application routing add-on deploys the following components:

-### Install or update the `aks-preview` Azure CLI extension

- ```azurecli-interactive

- az extension add --name aks-preview

- ```

- ```azurecli-interactive

- az extension update --name aks-preview

- ```

-### Create and export a self-signed SSL certificate

-> [!NOTE]

-> If you already have an SSL certificate, you can skip this step.

-1. Create a self-signed SSL certificate to use with the ingress using the `openssl req` command. Make sure you replace *`<Hostname>`* with the DNS name you're using.

- ```bash

- openssl req -new -x509 -nodes -out aks-ingress-tls.crt -keyout aks-ingress-tls.key -subj "/CN=<Hostname>" -addext "subjectAltName=DNS:<Hostname>"

- ```

-2. Export the SSL certificate and skip the password prompt using the `openssl pkcs12 -export` command.

- ```bash

- openssl pkcs12 -export -in aks-ingress-tls.crt -inkey aks-ingress-tls.key -out aks-ingress-tls.pfx

- ```

-### Create an Azure Key Vault to store the certificate

-> [!NOTE]

-> If you already have an Azure Key Vault, you can skip this step.

- ```azurecli-interactive

- az keyvault create -g <ResourceGroupName> -l <Location> -n <KeyVaultName>

- ```

-### Import certificate into Azure Key Vault

- ```azurecli-interactive

- az keyvault certificate import --vault-name <KeyVaultName> -n <KeyVaultCertificateName> -f aks-ingress-tls.pfx [--password <certificate password if specified>]

- ```

-### Create an Azure DNS zone

-> [!NOTE]

-> If you want the add-on to automatically manage creating host names via Azure DNS, you need to [create an Azure DNS zone](../dns/dns-getstarted-cli.md) if you don't have one already.

- ```azurecli-interactive

- az network dns zone create -g <ResourceGroupName> -n <ZoneName>

- ```

-# [Without Open Service Mesh (OSM)](#tab/without-osm)

-The following extra add-on is required:

-

-> [!IMPORTANT]

-> To enable the add-on to reload certificates from Azure Key Vault when they change, you should enable the [secret autorotation feature](./csi-secrets-store-configuration-options.md#enable-and-disable-auto-rotation) of the Secret Store CSI driver with the `--enable-secret-rotation` argument. When the autorotation is enabled, the driver updates the pod mount and the Kubernetes secret by polling for changes periodically, based on the rotation poll interval you can define. The default rotation poll interval is two minutes.

-### Enable application routing on a new cluster

- ```azurecli-interactive

- az aks create -g <ResourceGroupName> -n <ClusterName> -l <Location> --enable-addons azure-keyvault-secrets-provider,web_application_routing --generate-ssh-keys --enable-secret-rotation

- ```

-### Enable application routing on an existing cluster

- ```azurecli-interactive

- az aks enable-addons -g <ResourceGroupName> -n <ClusterName> --addons azure-keyvault-secrets-provider,web_application_routing --enable-secret-rotation

- ```

-# [With Open Service Mesh (OSM)](#tab/with-osm)

-The following extra add-ons are required:

-> [!IMPORTANT]

-> To enable the add-on to reload certificates from Azure Key Vault when they change, you should enable the [secret autorotation feature](./csi-secrets-store-configuration-options.md#enable-and-disable-auto-rotation) of the Secret Store CSI driver with the `--enable-secret-rotation` argument. When the autorotation is enabled, the driver updates the pod mount and the Kubernetes secret by polling for changes periodically, based on the rotation poll interval you can define. The default rotation poll interval is two minutes.

-### Enable application routing on a new cluster

- ```azurecli-interactive

- az aks create -g <ResourceGroupName> -n <ClusterName> -l <Location> --enable-addons azure-keyvault-secrets-provider,open-service-mesh,web_application_routing --generate-ssh-keys --enable-secret-rotation

- ```

-### Enable application routing on an existing cluster

- ```azurecli-interactive

- az aks enable-addons -g <ResourceGroupName> -n <ClusterName> --addons azure-keyvault-secrets-provider,open-service-mesh,web_application_routing --enable-secret-rotation

- ```

-# [With service annotations (retired)](#tab/service-annotations)

-> Configuring ingresses by adding annotations on the Service object is retired. Please consider [configuring via an Ingress object](?tabs=without-osm).

-The following extra add-on is required:

-> [!IMPORTANT]

-> To enable the add-on to reload certificates from Azure Key Vault when they change, you should enable the [secret autorotation feature](./csi-secrets-store-configuration-options.md#enable-and-disable-auto-rotation) of the Secret Store CSI driver with the `--enable-secret-rotation` argument. When the autorotation is enabled, the driver updates the pod mount and the Kubernetes secret by polling for changes periodically, based on the rotation poll interval you can define. The default rotation poll interval is two minutes.

-### Enable application routing on a new cluster

- ```azurecli-interactive

- az aks create -g <ResourceGroupName> -n <ClusterName> -l <Location> --enable-addons azure-keyvault-secrets-provider,web_application_routing --generate-ssh-keys --enable-secret-rotation

- ```

-### Enable application routing on an existing cluster

- ```azurecli-interactive

- az aks enable-addons -g <ResourceGroupName> -n <ClusterName> --addons azure-keyvault-secrets-provider,web_application_routing --enable-secret-rotation

- ```

-## Retrieve the add-on's managed identity object ID

-You use the managed identity in the next steps to grant permissions to manage the Azure DNS zone and retrieve secrets and certificates from the Azure Key Vault.

- ```azurecli-interactive

- # Provide values for your environment

- RGNAME=<ResourceGroupName>

- CLUSTERNAME=<ClusterName>

- MANAGEDIDENTITY_OBJECTID=$(az aks show -g ${RGNAME} -n ${CLUSTERNAME} --query ingressProfile.webAppRouting.identity.objectId -o tsv)

- ```

-## Configure the add-on to use Azure DNS to manage DNS zones

-> [!NOTE]

-> If you plan to use Azure DNS, you need to update the add-on to pass in the `--dns-zone-resource-id`.

-1. Retrieve the resource ID for the DNS zone using the [`az network dns zone show`][az-network-dns-zone-show] command and setting the output to a variable named *ZONEID*.

- ```azurecli-interactive

- ZONEID=$(az network dns zone show -g <ResourceGroupName> -n <ZoneName> --query "id" --output tsv)

- ```

-2. Grant **DNS Zone Contributor** permissions on the DNS zone using the [`az role assignment create`][az-role-assignment-create] command.

- ```azurecli-interactive

- az role assignment create --role "DNS Zone Contributor" --assignee $MANAGEDIDENTITY_OBJECTID --scope $ZONEID

- ```

-3. Update the add-on to enable the integration with Azure DNS and install the **external-dns** controller using the [`az aks addon update`][az-aks-addon-update] command.

- ```azurecli-interactive

- az aks addon update -g <ResourceGroupName> -n <ClusterName> --addon web_application_routing --dns-zone-resource-id=$ZONEID

- ```

-## Grant the add-on permissions to retrieve certificates from Azure Key Vault

-The application routing add-on creates a user-created managed identity in the cluster resource group. You need to grant permissions to the managed identity so it can retrieve SSL certificates from the Azure Key Vault.

-Azure Key Vault offers [two authorization systems](../key-vault/general/rbac-access-policy.md): **Azure role-based access control (Azure RBAC)**, which operates on the management plane, and the **access policy model**, which operates on both the management plane and the data plane. To find out which system your key vault is using, you can query the `enableRbacAuthorization` property.

-az keyvault show --name <KeyVaultName> --query properties.enableRbacAuthorization

-If Azure RBAC authorization is enabled for your key vault, you should configure permissions using Azure RBAC. Add the `Key Vault Secrets User` role assignment to the key vault.

-```azurecli-interactive

-KEYVAULTID=$(az keyvault show --name <KeyVaultName> --query "id" --output tsv)

-az role assignment create --role "Key Vault Secrets User" --assignee $MANAGEDIDENTITY_OBJECTID --scope $KEYVAULTID

-```

-If Azure RBAC authorization is not enabled for your key vault, you should configure permissions using the access policy model. Grant `GET` permissions for the application routing add-on to retrieve certificates from Azure Key Vault using the [`az keyvault set-policy`][az-keyvault-set-policy] command.

-az keyvault set-policy --name <KeyVaultName> --object-id $MANAGEDIDENTITY_OBJECTID --secret-permissions get --certificate-permissions get

- ```azurecli-interactive

- az aks get-credentials -g <ResourceGroupName> -n <ClusterName>

- ```

-Application routing uses annotations on Kubernetes ingress objects to create the appropriate resources, create records on Azure DNS, and retrieve the SSL certificates from Azure Key Vault.

-# [Without Open Service Mesh (OSM)](#tab/without-osm)

-### Create the application namespace

-### Create the deployment

-### Create the service

-### Create the ingress

-The application routing add-on creates an ingress class on the cluster called *webapprouting.kubernetes.azure.com*. When you create an ingress object with this class, it activates the add-on.

-1. Get the certificate URI to use in the ingress from Azure Key Vault using the [`az keyvault certificate show`][az-keyvault-certificate-show] command.

- ```azurecli-interactive

- az keyvault certificate show --vault-name <KeyVaultName> -n <KeyVaultCertificateName> --query "id" --output tsv

- ```

-2. Copy the following YAML into a new file named **ingress.yaml** and save the file to your local computer.

- > [!NOTE]

- > Update *`<Hostname>`* with your DNS host name and *`<KeyVaultCertificateUri>`* with the ID returned from Azure Key Vault.

- > The *`secretName`* key in the `tls` section defines the name of the secret that contains the certificate for this Ingress resource. This certificate will be presented in the browser when a client browses to the URL defined in the `<Hostname>` key. Make sure that the value of `secretName` is equal to `keyvault-` followed by the value of the Ingress resource name (from `metadata.name`). In the example YAML, secretName will need to be equal to `keyvault-aks-helloworld`.

- annotations:

- kubernetes.azure.com/tls-cert-keyvault-uri: <KeyVaultCertificateUri>

- tls:

- - hosts:

- - <Hostname>

- secretName: keyvault-<Ingress resource name>

-### Create the resources on the cluster

- kubectl apply -f service.yaml -n hello-web-app-routing

- kubectl apply -f ingress.yaml -n hello-web-app-routing

- The following example output shows the created resources:

- ingress.networking.k8s.io/aks-helloworld created

-# [With Open Service Mesh (OSM)](#tab/with-osm)

-### Create the application namespace

-1. Create a namespace called `hello-web-app-routing` to run the example pods using the `kubectl create namespace` command.

-### Create the deployment

- ```yaml

-### Create the service

- ```yaml

-### Create the ingress

-The application routing add-on creates an ingress class on the cluster called *webapprouting.kubernetes.azure.com*. When you create an ingress object with this class, it activates the add-on. The `kubernetes.azure.com/use-osm-mtls: "true"` annotation on the ingress object creates an Open Service Mesh (OSM) [IngressBackend](https://release-v1-2.docs.openservicemesh.io/docs/guides/traffic_management/ingress/#ingressbackend-api) to configure a backend service to accept ingress traffic from trusted sources.

-OSM issues a certificate that Nginx uses as the client certificate to proxy HTTPS connections to TLS backends. The client certificate and CA certificate are stored in a Kubernetes secret that Nginx uses to authenticate service mesh back ends. For more information, see [Open Service Mesh: Ingress with Kubernetes Nginx Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/).

-1. Get the certificate URI to use in the ingress from Azure Key Vault using the [`az keyvault certificate show`][az-keyvault-certificate-show] command.

- ```azurecli-interactive

- az keyvault certificate show --vault-name <KeyVaultName> -n <KeyVaultCertificateName> --query "id" --output tsv

- ```

-2. Copy the following YAML into a new file named **ingress.yaml** and save the file to your local computer.

- > [!NOTE]

- > Update *`<Hostname>`* with your DNS host name and *`<KeyVaultCertificateUri>`* with the ID returned from Azure Key Vault.

- > The *`secretName`* key in the `tls` section defines the name of the secret that contains the certificate for this Ingress resource. This certificate will be presented in the browser when a client browses to the URL defined in the `<Hostname>` key. Make sure that the value of `secretName` is equal to `keyvault-` followed by the value of the Ingress resource name (from `metadata.name`). In the example YAML, secretName will need to be equal to `keyvault-aks-helloworld`.

- ```yaml

- kubernetes.azure.com/tls-cert-keyvault-uri: <KeyVaultCertificateUri>

- tls:

- - hosts:

- - <Hostname>

- secretName: keyvault-<Ingress resource name>

-### Create the resources on the cluster

- kubectl apply -f service.yaml -n hello-web-app-routing

- kubectl apply -f ingress.yaml -n hello-web-app-routing

- The following example output shows the created resources:

-# [With service annotations (retired)](#tab/service-annotations)

-> Configuring ingresses by adding annotations on the Service object is retired. Please consider [configuring via an Ingress object](?tabs=without-osm).

-### Create the application namespace

-### Create the deployment

- ```yaml

-### Create the service with the annotations (retired)

- > [!NOTE]

- > Update *`<Hostname>`* with your DNS host name and *`<KeyVaultCertificateUri>`* with the ID returned from Azure Key Vault. This certificate will be presented in the browser.

- ```yaml

- annotations:

- kubernetes.azure.com/ingress-host: <Hostname>

- kubernetes.azure.com/tls-cert-keyvault-uri: <KeyVaultCertificateUri>

-### Create the resources on the cluster

- kubectl apply -f service.yaml -n hello-web-app-routing

- The following example output shows the created resources:

- service/aks-helloworld created

-## Verify the managed ingress was created

- ```bash

- kubectl get ingress -n hello-web-app-routing

- The following example output shows the created managed ingress:

- NAME CLASS HOSTS ADDRESS PORTS AGE

- aks-helloworld webapprouting.kubernetes.azure.com myapp.contoso.com 20.51.92.19 80, 443 4m

-## Access the endpoint over a DNS hostname

-If you haven't configured Azure DNS integration, you need to configure your own DNS provider with an `A` record pointing to the ingress IP address and the host name you configured for the ingress, for example *myapp.contoso.com*.

-1. Remove the associated namespace using the `kubectl delete namespace` command.

- ```bash

- kubectl delete namespace hello-web-app-routing

- ```

-2. Remove the application routing add-on from your cluster using the [`az aks disable-addons`][az-aks-disable-addons] command.

- ```azurecli-interactive

- az aks disable-addons --addons web_application_routing --name myAKSCluster --resource-group myResourceGroup

- ```

-[az-aks-create]: /cli/azure/aks#az-aks-create

-[az-aks-show]: /cli/azure/aks#az-aks-show

-[az-extension-add]: /cli/azure/extension#az-extension-add

-[az-extension-update]: /cli/azure/extension#az-extension-update

-[az-keyvault-create]: /cli/azure/keyvault#az_keyvault_create

-[az-keyvault-certificate-import]: /cli/azure/keyvault/certificate#az_keyvault_certificate_import

-[az-keyvault-certificate-show]: /cli/azure/keyvault/certificate#az_keyvault_certificate_show

-[az-network-dns-zone-create]: /cli/azure/network/dns/zone#az_network_dns_zone_create

-[az-network-dns-zone-show]: /cli/azure/network/dns/zone#az_network_dns_zone_show

-[az-role-assignment-create]: /cli/azure/role/assignment#az_role_assignment_create

-[az-aks-addon-update]: /cli/azure/aks/addon#az_aks_addon_update

-[az-keyvault-set-policy]: /cli/azure/keyvault#az_keyvault_set_policy

-[osm-release]: https://github.com/openservicemesh/osm/releases/

-[nginx]: https://kubernetes.github.io/ingress-nginx/

-[external-dns]: https://github.com/kubernetes-incubator/external-dns

-> We don't recommend running stateful containers, such as MongoDB and Rabbit MQ, without persistent storage for production. We use them here here for simplicity, but we recommend using managed services, such as Azure CosmosDB or Azure Service Bus.

-> This article describes restoring a database backup to a target server from a storage container in the source server's region. In some cases, restoring backups from a different region can have poor performance, especially for large databases. For the best performance during database restore, migrate or create a a new storage container in the target server region. Copy the .abf backup files from the source region storage container to the target region storage container prior to restoring the database to the target server. While out of scope for this article, in some cases, particularly with very large databases, scripting out a database from your source server, recreating, and then processing on the target server to load database data may be more cost effective than using backup/restore.

-> Built-in cache is volatile and is shared by all units in the same region in the same API Management service. Regardless of the cache type being used (internal or external), if the cache-related operations fail to connect to the cache due to the volatility of the cache or any other reason, the API call that uses the cache related operation doesn't raise an error, and the cache operation completes successfully. In the case of a read operation, a null value is returned to the calling policy expression. Your policy code should be designed to ensure that that there's a "fallback" mechanism to retrieve data not found in the cache.

-API Management uses a public IP address for a connection outside the VNet or a peered VNet and a private IP address for a connection in the VNet or a peered VNet.

- > When making OAuth 2.0-related changes, be sure to to republish the developer portal after every modification as relevant changes (for example, scope change) otherwise cannot propagate into the portal and subsequently be used in trying out the APIs.

-The `context.ParentResult` is set to the parent object for the current resolver execution. Consider the following partial schema:

-1. Configure the Microsoft Entra provider using the "Advanced" management mode, supplying the client ID and client secret values you collected in the previous step. For the Issuer URL, use Use `<authentication-endpoint>/<tenant-id>/v2.0`, and replace *\<authentication-endpoint>* with the [authentication endpoint for your cloud environment](../active-directory/develop/authentication-national-cloud.md#azure-ad-authentication-endpoints) (e.g., "https://login.microsoftonline.com" for global Azure), also replacing *\<tenant-id>* with your **Directory (tenant) ID**.

- "time": "2020-07-16T17:42:32.9322528Z",

- "ResourceId": "/SUBSCRIPTIONS/EF90E930-9D7F-4A60-8A99-748E0EEA69DE/RESOURCEGROUPS/FREEBERGDEMO/PROVIDERS/MICROSOFT.WEB/SITES/FREEBERG-WINDOWS",

- "User": "$freeberg-windows",

- "UserDisplayName": "$freeberg-windows",

-With the SQL Database protected by the virtual network, the easiest way to run Run [dotnet database migrations](/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli) is in an SSH session with the App Service container.

- 

-Azure Application Gateways are always deployed in a highly available fashion. The service is made out of multiple instances that are created as configured (if autoscaling is disabled) or required by the application load (if autoscaling is enabled). Note that from the user's perspective you don't necessarily have visibility into the individual instances, but just into the Application Gateway service as a whole. If a certain instance has a problem and stops being functional, Azure Application Gateway will transparently create a new instance.

-Even if you configure autoscaling with zero minimum instances the service will still be highly available, which is always included with the fixed price.

-However, creating a new instance can take some time (around six or seven minutes). If you don't want to have this downtime, you can configure a minimum instance count of two, ideally with Availability Zone support. This way you'll have at least two instances in your Azure Application Gateway under normal circumstances. So if one of them had a problem the other will try to handle the traffic while a new instance is being created. An Azure Application Gateway instance can support around 10 Capacity Units, so depending on how much traffic you typically have you might want to configure your minimum instance autoscaling setting to a value higher than two.

-For scale-in events, Application Gateway will drain existing connections for 5 minutes on the instance that is subject for removal. After 5 minutes, existing connections will be closed and the instance removed. Any new connections during or after the 5 minute scale-in time will be established to other existing instances on the same gateway.

-An HTTP 408 response can be observed when client requests to the frontend listener of application gateway don't respond back within 60 seconds. This error can be observed due to traffic congestion between on-premises networks and Azure, when virtual appliance inspects the traffic traffic, or the client itself becomes overwhelmed.

-* Navigate to the Log Analytics workspace linked to your Automation account. After after selecting the workspace, choose **Solutions** from the left pane. On the Solutions page, select **Start-Stop-VM[workspace]** from the list.

-1. Install the script to run to conduct migrations.

-1. Connect to your Azure Linux VM. If you used a password, you can use the syntax below. If you used a public-private key pair, see [SSH on Linux](./../virtual-machines/linux/mac-create-ssh-keys.md) for detailed steps. The other commands retrieve information about what packages can be installed, including what updates to currently installed packages packages are available, and installs Python.

-The first report may not be available immediately and may take up to 30 minutes after you enable a node. For more information about report data, see see [Using a DSC report server](/powershell/dsc/pull-server/reportserver).

-> The `.test.env` is a single set of of environment variables that drives the launcher's behavior. Generating it with care for a given environment will ensure reproducibility of the launcher's behavior.

-The connectivity mode provides you the flexibility to choose how much data is sent to Azure and how users interact with the Arc Data Controller. Depending on the connectivity mode that is chosen, some functionality of Azure Arc-enabled data services may or may not be available.

-Importantly, if the Azure Arc-enabled data services are directly connected to Azure, then users can use [Azure Resource Manager APIs](/rest/api/resources/), the Azure CLI, and the Azure portal to operate the Azure Arc data services. The experience in directly connected mode is much like how you would use any other Azure service with provisioning/de-provisioning, scaling, configuring, and so on all in the Azure portal. If the Azure Arc-enabled data services are indirectly connected to Azure, then the Azure portal is a read-only view. You can see the inventory of SQL managed instances and PostgreSQL servers that you have deployed and the details about them, but you cannot take action on them in the Azure portal. In the indirectly connected mode, all actions must be taken locally using Azure Data Studio, the appropriate CLI, or Kubernetes native tools like kubectl.

-Additionally, Microsoft Entra ID and Azure Role-Based Access Control can be used in the directly connected mode only because there is a dependency on a continuous and direct connection to Azure to provide this functionality.

-|**Description**|Indirectly connected mode offers most of the management services locally in your environment with no direct connection to Azure. A minimal amount of data must be sent to Azure for inventory and billing purposes _only_. It is exported to a file and uploaded to Azure at least once per month. No direct or continuous connection to Azure is required. Some features and services which require a connection to Azure will not be available.|Directly connected mode offers all of the available services when a direct connection can be established with Azure. Connections are always initiated _from_ your environment to Azure and use standard ports and protocols such as HTTPS/443.|No data can be sent to or from Azure in any way.|

-|**Typical use cases**|On-premises data centers that donΓÇÖt allow connectivity in or out of the data region of the data center due to business or regulatory compliance policies or out of concerns of external attacks or data exfiltration. Typical examples: Financial institutions, health care, government. <br/><br/>Edge site locations where the edge site doesnΓÇÖt typically have connectivity to the Internet. Typical examples: oil/gas or military field applications. <br/><br/>Edge site locations that have intermittent connectivity with long periods of outages. Typical examples: stadiums, cruise ships. | Organizations who are using public clouds. Typical examples: Azure, AWS or Google Cloud.<br/><br/>Edge site locations where Internet connectivity is typically present and allowed. Typical examples: retail stores, manufacturing.<br/><br/>Corporate data centers with more permissive policies for connectivity to/from their data region of the datacenter to the Internet. Typical examples: Non-regulated businesses, small/medium sized businesses|Truly "air-gapped" environments where no data under any circumstances can come or go from the data environment. Typical examples: top secret government facilities.|

-|**How data is sent to Azure**|There are three options for how the billing and inventory data can be sent to Azure:<br><br> 1) Data is exported out of the data region by an automated process that has connectivity to both the secure data region and Azure.<br><br>2) Data is exported out of the data region by an automated process within the data region, automatically copied to a less secure region, and an automated process in the less secure region uploads the data to Azure.<br><br>3) Data is manually exported by a user within the secure region, manually brought out of the secure region, and manually uploaded to Azure. <br><br>The first two options are an automated continuous process that can be scheduled to run frequently so there is minimal delay in the transfer of data to Azure subject only to the available connectivity to Azure.|Data is automatically and continuously sent to Azure.|Data is never sent to Azure.|

-|**Authentication**|Use local username/password for data controller and dashboard authentication. Use SQL and Postgres logins or Active Directory (AD is not currently supported) for connectivity to database instances. Use Kubernetes authentication providers for authentication to the Kubernetes API.|In addition to or instead of the authentication methods for the indirectly connected mode, you can _optionally_ use Microsoft Entra ID.|

-**All communication with Azure is always initiated from your environment.** This is true even for operations which are initiated by a user in the Azure portal. In that case, there is effectively a task, which is queued up in Azure. An agent in your environment initiates the communication with Azure to see what tasks are in the queue, runs the tasks, and reports back the status/completion/fail to Azure.

-|**Container images**|Microsoft Container Registry -> Customer|Required|No|Indirect or direct|Container images are the method for distributing the software. In an environment which can connect to the Microsoft Container Registry (MCR) over the Internet, the container images can be pulled directly from MCR. In the event that the deployment environment doesnΓÇÖt have direct connectivity, you can pull the images from MCR and push them to a private container registry in the deployment environment. At creation time, you can configure the creation process to pull from the private container registry instead of MCR. This will also apply to automated updates.|

-|**Monitoring data and logs**|Customer environment -> Azure|Optional|Maybe depending on data volume (see [Azure Monitor pricing](https://azure.microsoft.com/pricing/details/monitor/))|Indirect or direct|You may want to send the locally collected monitoring data and logs to Azure Monitor for aggregating data across multiple environments into one place and also to use Azure Monitor services like alerts, using the data in Azure Machine Learning, etc.|

-|**Azure Role-based Access Control (Azure RBAC)**|Customer environment -> Azure -> Customer Environment|Optional|No|Direct only|If you want to use Azure RBAC, then connectivity must be established with Azure at all times. If you donΓÇÖt want to use Azure RBAC then local Kubernetes RBAC can be used.|

-|**Microsoft Entra ID (Future)**|Customer environment -> Azure -> Customer environment|Optional|Maybe, but you may already be paying for Microsoft Entra ID|Direct only|If you want to use Microsoft Entra ID for authentication, then connectivity must be established with Azure at all times. If you donΓÇÖt want to use Microsoft Entra ID for authentication, you can use Active Directory Federation Services (ADFS) over Active Directory. **Pending availability in directly connected mode**|

-|**Azure backup - long term retention (Future)**| Customer environment -> Azure | Optional| Yes for Azure storage | Direct only |You may want to send backups that are taken locally to Azure Backup for long-term, off-site retention of backups and bring them back to the local environment for restore. |

-|**Provisioning and configuration changes from Azure portal**|Customer environment -> Azure -> Customer environment|Optional|No|Direct only|Provisioning and configuration changes can be done locally using Azure Data Studio or the appropriate CLI. In directly connected mode, you will also be able to provision and make configuration changes from the Azure portal.|

-In addition, resource bridge (preview) requires [Arc-enabled Kubernetes endpoints](../network-requirements-consolidated.md#azure-arc-enabled-kubernetes-endpoints).

-Azure Arc-enabled PostgreSQL server is the community version of PostgreSQL. So any tool that that works on PostgreSQL outside of Azure Arc should work with Azure Arc-enabled PostgreSQL server.

-As part of of the family of Azure SQL products, Azure Arc-enabled SQL Managed Instance is available in two [vCore](/azure/azure-sql/database/service-tiers-vcore) service tiers.

-The AzureML extension lets you deploy and run Azure Machine Learning on Azure Arc-enabled Kubernetes clusters.

-For more information, see [Introduction to Kubernetes compute target in AzureML](../../machine-learning/how-to-attach-kubernetes-anywhere.md) and [Deploy AzureML extension on AKS or Arc Kubernetes cluster](../../machine-learning/how-to-deploy-kubernetes-extension.md).

-The currently supported versions of the `microsoft.flux` extension are described below. The most recent version of the Flux v2 extension and the two previous versions (N-2) are supported. We generally recommend that you use the most recent version of the extension.

- By default, `waitForReconciliation` is set to false, so when creating a flux configuration, the `provisioningState` returns `Succeeded` once the configuration reaches the cluster and the ARM template or Azure CLI command successfully exits. However, the actual state of the objects being deployed as part of the configuration is tracked by `complianceState`, which can be viewed in the portal or by using Azure CLI. Setting `waitForReconciliation` to true and specifying a `reconciliationWaitDuration` means that the template or CLI deployment will wait for `complianceState` to reach a terminal state (success or failure) before exiting. ([Example](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/kubernetesconfiguration/resource-manager/Microsoft.KubernetesConfiguration/stable/2023-05-01/examples/CreateFluxConfiguration.json#L72))

-## Azure Arc resource bridge (preview)

-This section describes additional networking requirements specific to deploying Azure Arc resource bridge (preview) in your enterprise. These requirements also apply to Azure Arc-enabled VMware vSphere (preview) and Azure Arc-enabled System Center Virtual Machine Manager (preview).

-For more information, see [Azure Arc resource bridge (preview) network requirements](resource-bridge/network-requirements.md).

-## Azure Arc-enabled VMware vSphere (preview)

-For more information, see [Support matrix for Azure Arc-enabled VMware vSphere (preview)](vmware-vsphere/support-matrix-for-arc-enabled-vmware-vsphere.md).

-* Virtual machines (preview): Provision, resize, delete and manage virtual machines based on [VMware vSphere](./vmware-vsphere/overview.md) or [Azure Stack HCI](/azure-stack/hci/manage/azure-arc-vm-management-overview) and enable VM self-service through role-based access.

-description: Learn about the Azure CLI commands that can be used to manage your Azure Arc resource bridge (preview) deployment.

-# Azure Arc resource bridge (preview) deployment command overview

-This topic provides an overview of the [Azure CLI commands](/cli/azure/arcappliance) that are used to manage Arc resource bridge (preview) deployment, in the order in which they are typically used for deployment.

-description: Learn how to manage Azure Arc resource bridge (preview) so that it remains online and operational.

-# Azure Arc resource bridge (preview) maintenance operations

-To keep your Azure Arc resource bridge (preview) deployment online and operational, you may need to perform maintenance operations such as updating credentials or monitoring upgrades.

-To maintain the on-premises appliance VM, the [appliance configuration files generated during deployment](deploy-cli.md#az-arcappliance-createconfig) need to be saved in a secure location and made available on the management machine. The management machine used to perform maintenance operations must meet all of [the Arc resource bridge (preview) requirements](system-requirements.md).

-The following sections describe some of the most common maintenance tasks for Arc resource bridge (preview).

-If you experience problems with the appliance VM, the appliance configuration files may help with troubleshooting. You can include these files when you [open an Azure support request](../../azure-portal/supportability/how-to-create-azure-support-request.md).

-You may also want to [collect logs](/cli/azure/arcappliance/logs#az-arcappliance-logs-vmware), which requires you to pass credentials to the on-premises control center:

-You may need to delete Arc resource bridge due to deployment failures or when no longer needed. To do so, you'll need the appliance configuration files. The [delete command](deploy-cli.md#az-arcappliance-delete) is the recommended way to delete the bridge. This command deletes the on-premises appliance VM as well as the Azure resource and underlying components across the two environments.

-description: Learn about network requirements for Azure Arc resource bridge (preview) including URLs that must be allowlisted.

-# Azure Arc resource bridge (preview) network requirements

-This article describes the networking requirements for deploying Azure Arc resource bridge (preview) in your enterprise.

-Arc resource bridge communicates outbound securely to Azure Arc over TCP port 443. If the appliance needs to connect through a firewall or proxy server to communicate over the internet, it communicates outbound using the HTTPS protocol.

-In addition, Arc resource bridge (preview) requires connectivity to the [Arc-enabled Kubernetes endpoints](../network-requirements-consolidated.md?tabs=azure-cloud).

-description: Learn how to use Azure Arc resource bridge (preview) to support VM self-servicing on Azure Stack HCI, VMware, and System Center Virtual Machine Manager.

-# What is Azure Arc resource bridge (preview)?

-Azure Arc resource bridge (preview) is a Microsoft managed product that is part of the core Azure Arc platform. It is designed to host other Azure Arc services. In this release, the resource bridge supports VM self-servicing and management from Azure, for virtualized Windows and Linux virtual machines hosted in an on-premises environment on [Azure Stack HCI](/azure-stack/hci/manage/azure-arc-vm-management-overview), VMware ([Arc-enabled VMware vSphere](../vmware-vsphere/index.yml) preview), and System Center Virtual Machine Manager (SCVMM) ([Arc-enabled SCVMM](../system-center-virtual-machine-manager/index.yml) preview).

-Azure Arc resource bridge (preview) hosts other components such as [custom locations](..\platform\conceptual-custom-locations.md), cluster extensions, and other Azure Arc agents in order to deliver the level of functionality with the private cloud infrastructures it supports. This complex system is composed of three layers:

-Azure Arc resource bridge (preview) can host other Azure services or solutions running on-premises. For this preview, there are two objects hosted on the Arc resource bridge (preview):

-Custom locations and cluster extension are both Azure resources, which are linked to the Azure Arc resource bridge (preview) resource in Azure Resource Manager. When you create an on-premises VM from Azure, you can select the custom location, and that routes that *create action* to the mapped vCenter, Azure Stack HCI cluster, or SCVMM.

-## Benefits of Azure Arc resource bridge (preview)

-Through Azure Arc resource bridge (preview), you can accomplish the following for each private cloud infrastructure from Azure:

-You can connect an SCVMM management server to Azure by deploying Azure Arc resource bridgeΓÇ»(preview) in the VMM environment. Azure Arc resource bridge (preview) enables you to represent the SCVMM resources (clouds, VMs, templates etc.) in Azure and perform various operations on them:

-description: Security information about Azure resource bridge (preview).

-# Azure Arc resource bridge (preview) security overview

-This article describes the security configuration and considerations you should evaluate before deploying Azure Arc resource bridge (preview) in your enterprise.

-By default, a Microsoft Entra system-assigned [managed identity](../../active-directory/managed-identities-azure-resources/overview.md) is created and assigned to the Azure Arc resource bridge (preview). Azure Arc resource bridge currently supports only a system-assigned identity. The `clusteridentityoperator` identity initiates the first outbound communication and fetches the Managed Service Identity (MSI) certificate used by other agents for communication with Azure.

-Azure Arc resource bridge (preview) is represented as a resource in a resource group inside an Azure subscription. Access to this resource is controlled by standard [Azure role-based access control](../../role-based-access-control/overview.md). From the [**Access Control (IAM)**](../../role-based-access-control/role-assignments-portal.md) page in the Azure portal, you can verify who has access to your Azure Arc resource bridge (preview).

-description: Learn about system requirements for Azure Arc resource bridge (preview).

-# Azure Arc resource bridge (preview) system requirements

-This article describes the system requirements for deploying Azure Arc resource bridge (preview).

- - If using DHCP, then the address must be reserved and outside of the assignable DHCP range of IPs. No other machine on the network will use or receive this IP from DHCP. DHCP is generally not recommended because a change in IP address (ex: due to an outage) impacts the resource bridge availability.

- - If using DHCP, then the address must be reserved and outside of the assignable DHCP range of IPs. No other machine on the network will use or receive this IP from DHCP. DHCP is generally not recommended because a change in IP address (ex: due to an outage) impacts the resource bridge availability.

- - Must be from within the IP address prefix.

- - Internal and external DNS resolution.

- - If using a proxy, the proxy server has to be reachable from this IP and all IPs within the VM IP pool.

-description: This article tells how to troubleshoot and resolve issues with the Azure Arc resource bridge (preview) when trying to deploy or connect to the service.

-# Troubleshoot Azure Arc resource bridge (preview) issues

-This article provides information on troubleshooting and resolving issues that may occur while attempting to deploy, use, or remove the Azure Arc resource bridge (preview). The resource bridge is a packaged virtual machine, which hosts a *management* Kubernetes cluster. For general information, see [Azure Arc resource bridge (preview) overview](./overview.md).

-### Remote PowerShell is not supported

-If you run `az arcappliance` CLI commands for Arc Resource Bridge via remote PowerShell, you may experience various problems. For instance, you might see an [authentication handshake failure error when trying to install the resource bridge on an Azure Stack HCI cluster](#authentication-handshake-failure) or another type of error.

-Using `az arcappliance` commands from remote PowerShell is not currently supported. Instead, sign in to the node through Remote Desktop Protocol (RDP) or use a console session.

-When there are multiple attempts to deploy Arc resource bridge, expired credentials left on the management machine may cause future deployments to fail. The error will contain the message `Unavailable desc = connection closed before server preface received`. This error will surface in various `az arcappliance` commands including `validate`, `prepare` and `delete`.

-To resolve this error, the .wssd\python and .wssd\kva folders in the user profile directory need to be manually deleted from the management machine. Depending on where the deployment errored, there may not be a kva folder to delete. You can delete these folders manually by navigating to the user profile directory (typically `C:\Users\<username>`), then deleting the `.wssd\python` and `.wssd\kva` folders. After they are deleted, retry the command that failed.

-When you run the Azure CLI commands, the following error may be returned: *The refresh token has expired or is invalid due to sign-in frequency checks by conditional access.* The error occurs because when you sign in to Azure, the token has a maximum lifetime. When that lifetime is exceeded, you need to sign in to Azure again by using the `az login` command.

-When deploying Arc resource bridge, the bridge may appear to be successfully deployed, because no errors were encountered when running `az arcappliance deploy` or `az arcappliance create`. However, when viewing the bridge in Azure portal, you may see status shows as **Offline**, and `az arcappliance show` may show the `provisioningState` as **Failed**. This happens when required providers are not registered before the bridge is deployed.

-> Partner products (such as Arc-enabled VMware vSphere) may have their own required providers to register. To see additional providers that must be registered, see the product's documentation.

-Arc resource bridge consists of an appliance VM that is deployed to the on-premises infrastructure. The appliance VM maintains a connection to the management endpoint of the on-premises infrastructure using locally stored credentials. If these credentials are not updated, the resource bridge is no longer able to communicate with the management endpoint. This may cause problems when trying to upgrade the resource bridge or manage VMs through Azure.

-When trying to deploy Arc resource bridge, you may see an error that contains `back-off pulling image \\\"url"\\\: FailFastPodCondition`. This error is caused when the appliance VM can't reach the URL specified in the error. To resolve this issue, make sure the appliance VM meets system requirements, including internet access connectivity to [required allowlist URLs](network-requirements.md).

-If you receive an error that contains `Not able to connect to https://example.url.com`, check with your network administrator to ensure your network allows all of the required firewall and proxy URLs to deploy Arc resource bridge. For more information, see [Azure Arc resource bridge (preview) network requirements](network-requirements.md).

-When trying to set the configuration for Arc resource bridge, you may receive an error message similar to:

-Azure Arc resource bridge (preview) runs a Kubernetes cluster, and its control plane requires a static IP address. The IP address is specified in the `infra.yaml` file. If the IP address is assigned from a DHCP server, the address can change if not reserved. Rebooting the Azure Arc resource bridge (preview) or VM can trigger an IP address change, resulting in failing services.

-Intermittently, the resource bridge (preview) can lose the reserved IP configuration. This is due to the behavior described in [loss of VIPs when systemd-networkd is restarted](https://github.com/acassen/keepalived/issues/1385). When the IP address isn't assigned to the Azure Arc resource bridge (preview) VM, any call to the resource bridge API server will fail. As a result, you can't create any new resource through the resource bridge (preview), ranging from connecting to Azure Arc private cloud, create a custom location, create a VM, etc.

-To resolve this issue, reboot the resource bridge (preview) VM, and it should recover its IP address. If the address is assigned from a DHCP server, reserve the IP address associated with the resource bridge (preview).

-While trying to deploy Arc Resource Bridge, a "KVA timeout error" may appear. The "KVA timeout error" is a generic error that can be the result of a variety of network misconfigurations that involve the management machine, Appliance VM, or Control Plane IP not having communication with each other, to the internet, or required URLs. This communication failure is often due to issues with DNS resolution, proxy settings, network configuration, or internet access.

-To resolve the error, one or more network misconfigurations may need to be addressed. Follow the steps below to address the most common reasons for this error.

-1. When there is a problem with deployment, the first step is to collect logs by Appliance VM IP (not by kubeconfig, as the kubeconfig may be empty if deploy command did not complete). Problems collecting logs are most likely due to the management machine being unable to reach the Appliance VM.

- If a request times out, the management machine is not able to communicate with the IP(s). This could be caused by a closed port, network misconfiguration or a firewall block. Work with your network administrator to allow communication between the management machine to the Control Plane IP and Appliance VM IP.

-1. Appliance VM IP and Control Plane IP must be able to communicate with the management machine and vCenter endpoint (for VMware) or MOC cloud agent endpoint (for HCI). Work with your network administrator to ensure the network is configured to permit this. This may require adding a firewall rule to open port 443 from the Appliance VM IP and Control Plane IP to vCenter or port 65000 and 55000 for Azure Stack HCI MOC cloud agent. Review [network requirements for Azure Stack HCI](/azure-stack/hci/manage/azure-arc-vm-management-prerequisites#network-port-requirements) and [VMware](../vmware-vsphere/quick-start-connect-vcenter-to-arc-using-script.md) for Arc resource bridge.

-## Move Arc resource bridge location

-When running an `az arcappliance` command, you may see a connection error: `authentication handshake failed: x509: certificate signed by unknown authority`

-This is usually caused when trying to run commands from remote PowerShell, which is not supported by Azure Arc resource bridge.

-This error occurs when you run the Azure CLI commands in a 32-bit context, which is the default behavior. The vSphere SDK only supports running in a 64-bit context. The specific error returned from the vSphere SDK is `Unable to import ova of size 6GB using govc`. To resolve the error, install and use Azure CLI 64-bit.

-When you deploy the resource bridge on VMware vCenter, if you have been using the same template to deploy and delete the appliance multiple times, you may encounter the following error:

-When deploying the resource bridge on VMware vCenter, you may get an error saying that you have insufficient permission. To resolve this issue, make sure that the user account being used to deploy the resource bridge has all of the following privileges in VMware vCenter and then try again.

-**vSphere Tagging** 

-**Resource** 

-**Sessions** 

-**vApp** 

-**Virtual machine** 

- - Acquire disk lease 

- - Add existing disk 

- - Add new disk 

- - Add or remove device 

- - Advanced configuration 

- - Change CPU count 

- - Change Memory 

- - Change Settings 

- - Change resource 

- - Configure managedBy 

- - Display connection settings 

- - Extend virtual disk 

- - Modify device settings 

- - Query Fault Tolerance compatibility 

- - Query unowned files 

- - Reload from path 

- - Remove disk 

- - Rename 

- - Reset guest information 

- - Set annotation 

- - Toggle disk change tracking 

- - Toggle fork parent 

- - Upgrade virtual machine compatibility 

- - Create from existing 

- - Create new 

- - Register 

- - Remove 

- - Unregister 

- - Guest operation alias modification 

- - Guest operation modifications 

- - Guest operation program execution 

- - Guest operation queries 

- - Connect devices 

- - Console interaction 

- - Guest operating system management by VIX API 

- - Install VMware Tools 

- - Power off 

- - Power on 

- - Reset 

- - Suspend 

- - Allow disk access 

- - Allow file access 

- - Allow read-only disk access 

- - Allow virtual machine download 

- - Allow virtual machine files upload 

- - Clone virtual machine 

- - Deploy template 

- - Mark as template 

- - Mark as virtual machine 

- - Create snapshot 

- - Remove snapshot 

- - Revert to snapshot 

-description: Learn how to upgrade Arc resource bridge (preview) using either cloud-managed upgrade or manual upgrade.

-# Upgrade Arc resource bridge (preview)

-This article describes how Arc resource bridge (preview) is upgraded, and the two ways upgrade can be performed: cloud-managed upgrade or manual upgrade. Currently, some private cloud providers differ in how they handle Arc resource bridge upgrades. For more information, see the [Private cloud providers](#private-cloud-providers) section.

-For Arc-enabled VMware vSphere (preview), manual upgrade is available, and cloud-managed upgrade is supported for appliances on version 1.0.15 and higher. When Arc-enabled VMware vSphere announces General Availability, appliances on version 1.0.15 and higher will receive cloud-managed upgrade as the default experience. Appliances that are below version 1.0.15 must be manually upgraded. A manual upgrade only upgrades the appliance to the next version, not the latest version. If you have multiple versions to upgrade, then another option is to review the steps for [performing a recovery](/azure/azure-arc/vmware-vsphere/recover-from-resource-bridge-deletion), then delete the appliance VM and perform the recovery steps. This will deploy a new Arc resource bridge using the latest version and reconnect pre-existing Azure resources.

-[Azure Arc VM management (preview) on Azure Stack HCI](/azure-stack/hci/manage/azure-arc-vm-management-overview) supports upgrade of an Arc resource bridge on Azure Stack HCI, version 22H2 up until appliance version 1.0.14 and `az arcappliance` CLI extension version 0.2.33. These upgrades can be done through manual upgrade or a support request for cloud-managed upgrade. For subsequent upgrades, you must transition to Azure Stack HCI, version 23H2 (preview). In version 23H2 (preview), the LCM tool manages upgrades across all components as a "validated recipe" package. For more information, visit the [Arc VM management FAQ page](/azure-stack/hci/manage/azure-arc-vms-faq).

- | OmsAgentForLinux | Windows | 60%|

-This article provides information for troubleshooting issues that may occur configuring the Azure Connected Machine agent for Windows or Linux. Both the interactive and at-scale installation methods when configuring connection to the service are included. For general information, see [Azure Arc-enabled servers overview](./overview.md).

-Use the following table to identify and resolve issues when configuring the Azure Connected Machine agent. You'll need the `AZCM0000` ("0000" can be any four digit number) error code printed to the console or script output.

-| AZCM0026 | There is an error in network configuration or some critical services are temporarily unavailable | Check if the required endpoints are reachable (for example, hostnames are resolvable, endpoints aren't blocked). If the network is configured for Private Link Scope, a Private Link Scope resource ID must be provided for onboarding using the `--private-link-scope` parameter. |

-| AZCM0041 | The credentials supplied are invalid | For device logins, verify that the user account specified has access to the tenant and subscription where the server resource will be created^{[1](#footnote3)}.<br> For service principal logins, check the client ID and secret for correctness, the expiration date of the secret^{[2](#footnote4)}, and that the service principal is from the same tenant where the server resource will be created^{[1](#footnote3)}.<br> <a name="footnote3"></a>¹See [How to find your Microsoft Entra tenant ID](/azure/active-directory-b2c/tenant-management-read-tenant-name).<br> <a name="footnote4"></a>²In Azure portal, open Microsoft Entra ID and select the App registration blade. Select the application to be used and the Certificates and secrets within it. Check whether the expiration data has passed. If it has, create new credentials with sufficient roles and try again. See [Connected Machine agent prerequisites-required permissions](prerequisites.md#required-permissions). |

-| AZCM0042 | Creation of the Azure Arc-enabled server resource failed | Review the error message in the output to identify the cause of the failure to create resource and the suggested remediation. For permission issues, see [Connected Machine agent prerequisites-required permissions](prerequisites.md#required-permissions) for more information. |

-| AZCM0043 | Deletion of the Azure Arc-enabled server resource failed | Verify that the user/service principal specified has permissions to delete Azure Arc-enabled server/resources in the specified group ΓÇö see [Connected Machine agent prerequisites-required permissions](prerequisites.md#required-permissions).<br> If the resource no longer exists in Azure, use the `--force-local-only` flag to proceed. |

-|Failed to acquire authorization token device flow |`Error occurred while sending request for Device Authorization Code: Post https://login.windows.net/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/devicecode?api-version=1.0: dial tcp 40.126.9.7:443: connect: network is unreachable.` |Cannot reach `login.windows.net` endpoint | Verify connectivity to the endpoint. |

-|Failed to acquire authorization token device flow |`Error occurred while sending request for Device Authorization Code: Post https://login.windows.net/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/devicecode?api-version=1.0: dial tcp 40.126.9.7:443: connect: network is Forbidden`. |Proxy or firewall is blocking access to `login.windows.net` endpoint. | Verify connectivity to the endpoint and it is not blocked by a firewall or proxy server. |

-|Failed to acquire authorization token from SPN |`Failed to execute the refresh request. Error = 'Post https://login.windows.net/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/token?api-version=1.0: Forbidden'` |Proxy or firewall is blocking access to `login.windows.net` endpoint. |Verify connectivity to the endpoint and it is not blocked by a firewall or proxy server. |

-| Failed to acquire authorization token from SPN |`Application with identifier 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' was not found in the directory 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant` |Incorrect service principal and/or Tenant ID. |Verify the service principal and/or the tenant ID.|

-|Failed to AzcmagentConnect ARM resource |`The subscription is not registered to use namespace 'Microsoft.HybridCompute'` |Azure resource providers are not registered. |Register the [resource providers](prerequisites.md#azure-resource-providers). |

-|Failed to AzcmagentConnect ARM resource |`Get https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.HybridCompute/machines/MSJC01?api-version=2019-03-18-preview: Forbidden` |Proxy server or firewall is blocking access to `management.azure.com` endpoint. |Verify connectivity to the endpoint and it is not blocked by a firewall or proxy server. |

-If you don't see your problem here or you can't resolve your issue, try one of the following channels for additional support:

-> * Depending on the version of the SDK and [storage provider](durable-functions-storage-providers.md) being used, long timers of 6 days or more may be internally implemented using a series of shorter timers (e.g., of 3 day durations) until the desired expiration time is reached. This can be observed in the underlying data store but won't impact the the orchestration behavior.

- // If only the event is passed, an Event Hubs partition to be be assigned via

-By default this command creates a project that runs in-process with the Functons host on the current [Long-Term Support (LTS) version of .NET Core]. You can use the `--target-framework` option to target a specific supported version of .NET, including .NET Framework. For for information, see the [`func init`](functions-core-tools-reference.md#func-init) reference.

-> The Azure Enterprise (EA) portal is getting retired. We recommend that both direct and indirect EA Azure Government customers use Cost Management + Billing in the Azure Government portal to manage their enrollment and billing instead of using the EA portal.

- > Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is is how you reference the drawing package you uploaded into your Azure storage account from your source code and HTTP requests.

-> Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is is how you reference the GeoJSON package you uploaded into your Azure storage account from your source code and HTTP requests.

-> The Power BI Visual bubble layer **Bubble size scaling** settings were deprecated starting in the September 2023 release of Power BI. You can no longer create reports using these settings, but existing reports will continue to work. It is recomended that you upgrade existing reports that use these settings to the new **range scaling** property. To upgrade to to the new **range scaling** property, select the desired option in the **Range scaling** drop-down list:

- Changes that may be required:

-

-

-

-

-

-

-

-

-

-| `satellite_with_roads` | No | Yes | Satellite and aerial imagery, with labels and road lines overlaid. On a global scale, there's an unlimited number of color combinations that may occur between the overlaid data and the imagery. A focus on making labels readable in most common scenarios, however, in some places the color contrast with the background imagery may make labels difficult to read. |

-

-> Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is is how you reference the GeoJSON package you uploaded into your Azure storage account from your source code and HTTP requests.

-It's helpful to visualize the charging stations and the boundary for the maximum reachable range of the electric vehicle on a map. Follow the steps outlined in the [How to create data registry] article to upload the boundary data and charging stations data as geojson objects to your [Azure storage account] then register them in your Azure Maps account. Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is is how you reference the geojson objects you uploaded into your Azure storage account from your source code.

-To help visualize the route, follow the steps outlined in the [How to create data registry] article to upload the route data as a geojson object to your [Azure storage account] then register it in your Azure Maps account. Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is is how you reference the geojson objects you uploaded into your Azure storage account from your source code. Then, call the rendering service, [Get Map Image API], to render the route on the map, and visualize it.

-> Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is is how you reference the geofence you uploaded into your Azure storage account from your source code and HTTP requests.

-

-# The customer can modify the the csv by adding/removing rows if needed

-where *VMSS1-autoscale.json* is the the file containing the JSON object below.

-Multi-line logging feature can be enabled by setting **enabled** flag to "true" under the `[log_collection_settings.enable_multiline_logs]` section in the the [config map](https://github.com/microsoft/Docker-Provider/blob/ci_prod/kubernetes/container-azm-ms-agentconfig.yaml)

-

-

-

-

- 

- 

- 

- 

- 

- 

- 

- 

- 

- [](media/data-collection-endpoint-overview/data-collection-endpoint-overview.png#lightbox)

- [](media/data-collection-endpoint-overview/data-collection-endpoint-basics.png#lightbox)

-

-

-

-

-

-

-Sometimes the charts might show no data after selecting correct resources and metrics. This behavior can be caused by several of the following reasons:

-In Azure, access to metrics is controlled by [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md). You must be a member of [monitoring reader](../../role-based-access-control/built-in-roles.md#monitoring-reader), [monitoring contributor](../../role-based-access-control/built-in-roles.md#monitoring-contributor), or [contributor](../../role-based-access-control/built-in-roles.md#contributor) to explore metrics for any resource.

-Some resources donΓÇÖt constantly emit their metrics. For example, Azure won't collect metrics for stopped virtual machines. Other resources might emit their metrics only when some condition occurs. For example, a metric showing processing time of a transaction requires at least one transaction. If there were no transactions in the selected time range, the chart will naturally be empty. Additionally, while most of the metrics in Azure are collected every minute, there are some that are collected less frequently. See the metric documentation to get more details about the metric that you're trying to explore.

-**Solution:** If you see a blank chart or your chart only displays part of metric data, verify that the difference between start- and end- dates in the time picker doesn't exceed the 30-day interval. Once you have selected a 30 day interval, you can [pan](metrics-charts.md#pan) the chart to view the full retention window.

-Azure metrics charts use dashed line style to indicate that there's a missing value (also known as ΓÇ£null valueΓÇ¥) between two known time grain data points. For example, if in the time selector you picked ΓÇ£1 minuteΓÇ¥ time granularity but the metric was reported at 07:26, 07:27, 07:29, and 07:30 (note a minute gap between second and third data points), then a dashed line will connect 07:27 and 07:29 and a solid line will connect all other data points. The dashed line drops down to zero when the metric uses **count** and **sum** aggregation. For the **avg**, **min** or **max** aggregations, the dashed line connects two nearest known data points. Also, when the data is missing on the rightmost or leftmost side of the chart, the dashed line expands to the direction of the missing data point.

- 

- 

-Azure monitor metrics uses SI based prefixes. Metrics will only be using IEC prefixes if the resource provider has chosen an appropriate unit for a metric.

-

-

-In many cases, the perceived drop in the metric values is a misunderstanding of the data shown on the chart. You can be misled by a drop in sums or counts when the chart shows the most-recent minutes because the last metric data points havenΓÇÖt been received or processed by Azure yet. Depending on the service, the latency of processing metrics can be within a couple minutes range. For charts showing a recent time range with a 1- or 5- minute granularity, a drop of the value over the last few minutes becomes more noticeable:

- 

-**Solution:** This behavior is by design. We believe that showing data as soon as we receive it's beneficial even when the data is *partial* or *incomplete*. Doing so allows you to make important conclusion sooner and start investigation right away. For example, for a metric that shows the number of failures, seeing a partial value X tells you that there were at least X failures on a given minute. You can start investigating the problem right away, rather than wait to see the exact count of failures that happened on this minute, which might not be as important. The chart will update once we receive the entire set of data, but at that time it may also show new incomplete data points from more recent minutes.

-

-

-

-

-

-

-#customer-intent: As a DevOps manager or data scientist, I want to understand which AIOps features Azure Monitor offers and how to implement a machine learning pipeline on data in Azure Monitor Logs so that I can use artifical intelligence to to improve service quality and reliability of my IT environment.

-

-

-

-

-

-

-

-

-

-

-

-

-

-

-

-

-[](media/customer-managed-keys/cmk-overview.png#lightbox)

-[](media/customer-managed-keys/soft-purge-protection.png#lightbox)

- [<img src="media/customer-managed-keys/grant-key-vault-permissions-8bit.png" alt="Screenshot of Grant Key Vault access policy permissions." title="Grant Key Vault access policy permissions" width="80%"/>](media/customer-managed-keys/grant-key-vault-permissions-8bit.png#lightbox)

-[](media/customer-managed-keys/key-identifier-8bit.png#lightbox)

-[  ](media/customer-managed-keys/cmk-workbook.png#lightbox)

-

-

-

-

-

-

-

- :::image type="content" source="media/manage-cost-storage/manage-cost-change-retention-01.png" alt-text="Screenshot that shows changing the workspace data retention setting.":::

-

-

- 

- 

- 

-

-

-

-

-[](media/log-analytics-overview/start-log-analytics.png#lightbox)

-[](media/log-analytics-overview/log-analytics.png#lightbox)

-[](media/data-platform-logs/logs-structure.png#lightbox)

-Workspace-based applications in Application Insights store their data in a Log Analytics workspace and use the same standard columns as other other tables in the workspace. Classic applications store their data separately and have different standard columns as specified in this article.

-[](media/logs-data-export/data-export-overview.png#lightbox)

-[](media/logs-data-export/storage-data-expand.png#lightbox)

-[](media/logs-data-export/storage-account-network.png#lightbox)

- [](media/logs-data-export/export-create-1.png#lightbox)

- [](media/logs-data-export/export-view-1.png#lightbox)

- <img src="media/logs-data-export/export-view-2.png" alt="Screenshot of data export rule view." title= "Data export rule configuration view" width="65%"/>

-[](media/logs-data-export/export-disable.png#lightbox)

-[](media/logs-data-export/export-delete.png#lightbox)

-[](media/logs-data-export/export-view.png#lightbox)

-[](media/logs-export-logic-app/logic-app-overview.png#lightbox)

- [](media/logs-export-logic-app/create-logic-app.png#lightbox)

-[](media/logs-export-logic-app/recurrence-action.png#lightbox)

- [](media/logs-export-logic-app/select-azure-monitor-connector.png#lightbox)

- [](media/logs-export-logic-app/select-query-action-list.png#lightbox)

- [](media/logs-export-logic-app/run-query-list-action.png#lightbox)

- [](media/logs-export-logic-app/select-parse-json.png#lightbox)

- [](media/logs-export-logic-app/select-body.png#lightbox)

- [](media/logs-export-logic-app/parse-json-payload.png#lightbox)

- [](media/logs-export-logic-app/select-compose.png#lightbox)

- [](media/logs-export-logic-app/select-body-compose.png#lightbox)

- [](media/logs-export-logic-app/select-create-blob.png#lightbox)

- [](media/logs-export-logic-app/blob-expression.png#lightbox)

- [](media/logs-export-logic-app/create-blob.png#lightbox)

-[](media/logs-export-logic-app/runs-history.png#lightbox)

-[](media/logs-export-logic-app/blob-data.png#lightbox)

-

-

- [](media/move-workspace/delete-solutions.png#lightbox)

- [](media/move-workspace/delete-rules.png#lightbox)

- [](media/move-workspace/portal.png#lightbox)

- 

- 

-

-[](./media/private-link-security/dns-zone-privatelink-monitor-azure-com-expanded-with-endpoint.png#lightbox)

-[](./media/private-link-security/dns-zone-privatelink-compressed-endpoints.png#lightbox)

-

-

-

-

-

-

-

- 

-

-

-

-[](media/queries/queries-button.png#lightbox)

-[](media/queries/query-sidebar.png#lightbox)

-[](media/queries/example-query-groupby.png#lightbox)

-[](media/queries/example-query-filter.png#lightbox)

- [ ](media/query-audit/diagnostic-setting-monitor.png#lightbox)

- [ ](media/query-audit/diagnostic-setting-workspace.png#lightbox)

-[](media/query-packs/view-query-pack.png#lightbox)

-[](media/save-query/save-query.png#lightbox)

-[](media/save-query/save-query-dialog.png#lightbox)

-The query scope defines the records that are evaluated by the query. This will usually include all records in a single Log Analytics workspace or Application Insights application. Log Analytics also allows you to set a scope for a particular monitored Azure resource. This allows a resource owner to focus only on their data, even if that resource writes to multiple workspaces.

-

-The scope is determined by the method you use to start Log Analytics, and in some cases you can change the scope by clicking on it. The following table lists the different types of scope used and different details for each.

-| Resource group | Records created by all resources in the resource group. May include data from multiple Log Analytics workspaces. | Select **Logs** from the resource group menu. | Cannot change scope.|

-| Subscription | Records created by all resources in the subscription. May include data from multiple Log Analytics workspaces. | Select **Logs** from the subscription menu. | Cannot change scope. |

-| Other Azure resources | Records created by the resource. May include data from multiple Log Analytics workspaces. | Select **Logs** from the resource menu.<br>OR<br>Select **Logs** from the **Azure Monitor** menu and then select a new scope. | Can only change scope to same resource type. |

-You can't use the following commands in a query when scoped to a resource since the query scope will already include any workspaces with data for that resource or set of resources:

-Setting the scope to a resource or set of resources is a particularly powerful feature of Log Analytics since it allows you to automatically consolidate distributed data in a single query. It can significantly affect performance though if data needs to be retrieved from workspaces across multiple Azure regions.

-Your query will receive a warning if the scope includes workspaces in 5 or more regions. it will still run, but it may take excessive time to complete.

-

-Your query will be blocked from running if the scope includes workspaces in 20 or more regions. In this case you will be prompted to reduce the number of workspace regions and attempt to run the query again. The dropdown will display all of the regions in the scope of the query, and you should reduce the number of regions before attempting to run the query again.

-

-

-

-If you use the [workspace](../logs/workspace-expression.md) or [app](../logs/app-expression.md) command to retrieve data from another workspace or classic application, the time picker may behave differently. If the scope is a Log Analytics workspace and you use **app**, or if the scope is a classic Application Insights application and you use **workspace**, then Log Analytics may not understand that the column used in the filter should determine the time filter.

-

-

- :::image type="content" source="./media/profiler-troubleshooting/search-trace-messages.png" alt-text="Screenshot that shows selecting the Search button from the Application Insights resource.":::

- :::image type="content" source="./media/profiler-troubleshooting/search-results.png" alt-text="Screenshot that shows the search results from aforementioned search string.":::

- :::image type="content" source="./media/profiler-troubleshooting/profiler-web-job.png" alt-text="Screenshot that shows the WebJobs pane, which displays the name, status, and last runtime of jobs.":::

- :::image type="content" source="./media/profiler-troubleshooting/profiler-web-job-log.png" alt-text="Screenshot that shows the Continuous WebJob Details pane.":::

-

-| Insights | Displays VM insights views if If the VM is enabled for [VM insights](../vm/vminsights-overview.md).<br><br>Select the **Performance** tab to view trends of critical performance counters over different periods of time. When you open VM insights from the virtual machine menu, you also have a table with detailed metrics for each disk. For details on how to use the Map view for a single machine, see [Chart performance with VM insights](vminsights-performance.md#view-performance-directly-from-an-azure-vm).<br><br>If *processes and dependencies* is enabled for the VM, select the **Map** tab to view the running processes on the machine, dependencies on other machines, and external processes. For details on how to use the Map view for a single machine, see [Use the Map feature of VM insights to understand application components](vminsights-maps.md#view-a-map-from-a-vm).<br><br>If the VM is not enabled for VM insights, it offers the option to enable VM insights. |

-1. **Networking:** You need to decide on the networking architecture. To use Azure NetApp Files, you need to create create a VNet that will host a delegated subnet for the Azure NetApp Files storage endpoints (IPs). To ensure that the size of this subnet is large enough, see [Considerations about delegating a subnet to Azure NetApp Files](azure-netapp-files-delegate-subnet.md#considerations).

-7. Change the read-only export policy back to the original export policy. See See [Configure export policy for NFS or dual-protocol volumes](azure-netapp-files-configure-export-policy.md).

- > Using the Security privilege users feature relies on the [SMB Continuous Availability Shares feature](azure-netapp-files-create-volumes-smb.md#continuous-availability). SMB Continuous Availability is **not** supported on custom applications. It is is only supported for workloads using Citrix App Laying, [FSLogix user profile containers](../virtual-desktop/create-fslogix-profile-container.md), and Microsoft SQL Server (not Linux SQL Server).

- No transfer operation is in progress and future transfers are not disabled.

- A transfer operation is in progress and future transfers are not disabled.

-Follow the following steps to create [alert rules in Azure Monitor](../azure-monitor/alerts/alerts-overview.md) to help you monitor the status of cross-region replication:

-1. From Azure Monitor, select **Alerts**.

-2. From the Alerts window, select the **Create** dropdown and select **Create new alert rule**.

-3. From the Scope tab of the Create an Alert Rule page, select **Select scope**. The **Select a Resource** page appears.

-4. From the Resource tab, find the **Volumes** resource type.

-5. From the Condition tab, select **Add condition**. From there, find a signal called ΓÇ£**is volume replication healthy**ΓÇ¥.

-6. There you'll see **Condition of the relationship, 1 or 0** and the **Configure Signal Logic** window is displayed.

-7. To check if the replication is _unhealthy_:

- * Set **Operator** to `Less than`.

- * Set **Aggregation type** to `Average`.

- * Set **Threshold** value to `1`.

- * Set **Unit** to `Count`.

-8. To check if the replication is _healthy_:

- * Set **Operator** to `Greater than or equal to`.

- * Set **Aggregation** type to `Average`.

- * Set **Threshold** value to `1`.

- * Set **Unit** to `Count`.

-9. Select **Review + create**. The alert rule is ready for use.

->If you're using using Standard network features, you should ensure that any User Defined Routes (UDRs) or Network Security Group (NSG) rules do not block Azure NetApp Files network communication with AD DS domain controllers assigned to the Azure NetApp Files AD DS site.

-For a list of regions that that currently support availability zones, see [Azure regions with availability zone support](../reliability/availability-zones-service-support.md).

-To use the `--no-restore` switch, you must have Bicep CLI version **0.4.1008 or later**.

-To use the publish command, you must have Bicep CLI version **0.4.1008 or later**. To use the `--documentationUri`/`-d` parameter, you must have Bicep CLI version **0.14.46 or later**.

-To use the restore command, you must have Bicep CLI version **0.4.1008 or later**. This command is currently only available when calling the Bicep CLI directly. It's not currently available through the Azure CLI command.

-Bicep CLI version 0.20.4 (c9422e016d)

-This function requires **Bicep version 0.5.6 or later**.

-This function requires **Bicep version 0.5.6 or later**.

-This function requires **Bicep version 0.4.412 or later**.

-This function requires **Bicep version 0.7.4 or later**.

-This function requires **Bicep version >0.16.2**.

-This function requires **Bicep version 0.4.412 or later**.

-> The lambda functions are only supported in Bicep CLI version 0.10.61 or newer.

-With **Bicep version 0.4.412 or later**, you call the list function by using the [accessor operator](operators-access.md#function-accessor). For example, `storageAccount.listKeys()`.

-| Microsoft.EventGrid/domains | [listKeys](/rest/api/eventgrid/controlplane-version2022-06-15/domains/list-shared-access-keys) |

-| Microsoft.EventGrid/topics | [listKeys](/rest/api/eventgrid/controlplane-version2022-06-15/topics/list-shared-access-keys) |

-| Microsoft.MachineLearningServices/workspaces/computes | [listKeys](/rest/api/azureml/2023-04-01/compute/list-keys) |

-| Microsoft.MachineLearningServices/workspaces/computes | [listNodes](/rest/api/azureml/2023-04-01/compute/list-nodes) |

-| Microsoft.MachineLearningServices/workspaces | [listKeys](/rest/api/azureml/2023-04-01/workspaces/list-keys) |

-This function requires **Bicep version 0.8.2 or later**.

-> [Bicep version 0.23 or newer](./install.md) is required to use this feature. The experimental feature `compileTimeImports` must be enabled from the [Bicep config file](./bicep-config.md#enable-experimental-features). For user-defined functions, the experimental feature `userDefinedFunctions` must also be enabled.

-> [Bicep version 0.23.X or newer](./install.md) is required to use this feature. The experimental feature `compileTimeImports` must be enabled from the [Bicep config file](./bicep-config.md#enable-experimental-features). For user-defined functions, the experimental feature `userDefinedFunctions` must also be enabled.

-Arrays start with a left bracket (`[`) and end with a right bracket (`]`). In Bicep, an array can be declared in single line or multiple lines. Commas (`,`) are used between values in single-line declarations, but not used in multiple-line declarations, You can mix and match single-line and multiple-line declarations. The multiple-line declaration requires **Bicep version 0.7.4 or later**.

-Objects start with a left brace (`{`) and end with a right brace (`}`). In Bicep, an object can be declared in single line or multiple lines. Each property in an object consists of key and value. The key and value are separated by a colon (`:`). An object allows any property of any type. Commas (`,`) are used between properties for single-line declarations, but not used between properties for multiple-line declarations. You can mix and match single-line and multiple-line declarations. The multiple-line declaration requires **Bicep version 0.7.4 or later**.

-With Azure CLI version 2.53.0 or later, and Bicep CLI version 0.22.6 or later, you can deploy a Bicep file by utilizing a Bicep parameter file. With the `using` statement within the Bicep parameters file, there's no need to provide the `--template-file` switch when specifying a Bicep parameter file for the `--parameters` switch. Including the `--template-file` switch will result in an "Only a .bicep template is allowed with a .bicepparam file" error.

-With Azure PowerShell version 10.4.0 or later, and Bicep CLI version 0.22.6 or later, you can deploy a Bicep file by utilizing a Bicep parameter file. With the `using` statement within the Bicep parameters file, there is no need to provide the `-TemplateFile` switch when specifying a Bicep parameter file for the `-TemplateParameterFile` switch.

-The deployment stack 'myStack' you're trying to create already already exists in the current subscription/management group/resource group. Do you want to overwrite it? Detaching: resources, resourceGroups (Y/N)

-You can now use multiple lines in function, array and object declarations. This feature requires **Bicep version 0.7.4 or later**.

-> The installation of Bicep CLI version 0.16 or newer does not need Gatekeeper exception. However, [nightly builds](#install-the-nightly-builds) of the Bicep CLI still require the exception.

-The ARM template [`references`](../templates/template-functions-resource.md#references) function returns an array of objects representing a resource collection's runtime states. In Bicep, there is no explicit references function. Instead, symbolic collection usage is employed directly, and during code generation, Bicep translates it to an ARM template that utilizes the ARM template references function. For the translation feature that transforms symbolic collections into ARM templates using the references function, it is necessary to have Bicep CLI version 0.20.4 or a more recent version. Additionally, in the [`bicepconfig.json`](./bicep-config.md#enable-experimental-features) file, the `symbolicNameCodegen` setting should be presented and set to `true`.

-The functionality relies on the following NuGet packages. The latest NuGet package versions match the latest Bicep version.

-When the value to return depends on a condition in the deployment, use the the `?` operator.

-You can define and use variables. Bicep CLI version 0.21.1 or newer is required for using variables in .bicepparam file. Here are some examples:

-With Azure CLI version 2.53.0 or later, and Bicep CLI version 0.22.6 or later, you can deploy a Bicep file by utilizing a Bicep parameter file. With the `using` statement within the Bicep parameters file, there is no need to provide the `--template-file` switch when specifying a Bicep parameter file for the `--parameters` switch. Including the `--template-file` switch will result in an "Only a .bicep template is allowed with a .bicepparam file" error.

-For more information, see [Deploy resources with Bicep and Azure CLI](./deploy-cli.md#parameters).

-[Bicep version 0.12.1 or newer](./install.md) is required to use this feature.

-To declare a custom tagged union data type within a Bicep file, you can place a discriminator decorator above a user-defined type declartion. [Bicep version 0.21.1 or newer](./install.md) is required to use this decorator. The syntax is:

-The parameter value is validated based on the discriminated property value. In the preceeding example, if the *serviceConfig* parameter value is of type *foo*, it undergoes validation using the *FooConfig*type. Likewise, if the parameter value is of type *bar*, validation is performed using the *BarConfig* type, and this pattern continues for other types as well.

-[Bicep version 0.21.1 or newer](./install.md) is required to use this compile-time import feature. The experimental flag `compileTimeImports` must be enabled from the [Bicep config file](./bicep-config.md#enable-experimental-features).

-[Bicep version 0.20 or newer](./install.md) is required to use this feature.

-With [Bicep version 0.23 or newer](./install.md), you have the flexibility to invoke another user-defined function within a user-defined function. In the preceding example, with the function definition of `sayHelloString`, you can redefine the `sayHelloObject` function as:

- :::image type="content" source="media/deploy-marketplace-app-quickstart/mrg-apps.png" alt-text="Screenshot of the managed resource group that that highlights the deployments and list of deployed resources.":::

-To use an existing application, choose **Select Existing** and then select **Make selection**. Use the **Select an application** dialog box to search for the application's name. From the results, select the the application and then the **Select** button. After you select an application, the control displays the **Authentication Type** to enter a password or certificate thumbprint.

-* One is client-server pattern that [clients send events the the server](./quickstarts-event-notifications-from-clients.md) and [server pushes messages to the clients](./quickstarts-push-messages-from-server.md).

- 

-> For eg, if the generated password is *ContosoVM_wcus_GUID*, then then geo-name is wcus and the URL would be: <`https://pod01-rec2.wcus.backup.windowsazure.com`><br><br>

- 

- 

-Vault and Resource Guard are **in different subscriptions but the same tenant.** </br> The Backup admin doesn't have access to the Resource Guard or the corresponding subscription. | Medium isolation between the Backup admin and the Security admin. | Relatively medium ease of implementation since two subscriptions (but a single tenant) are required. | Ensure that that permissions/ roles are correctly assigned for the resource or the subscription.

-But there are scenarios in which this capability isn't required. An Azure Recovery Services vault can't be deleted if there are backup items within it, even soft-deleted ones. This may pose a problem if the vault needs to be immediately deleted. For for example: deployment operations often clean up the created resources in the same workflow. A deployment can create a vault, configure backups for an item, do a test restore and then proceed to delete the backup items and the vault. If the vault deletion fails, the entire deployment might fail. Disabling soft-delete is the only way to guarantee immediate deletion.

-If you use a Microsoft Entra application to create a custom image pool with an Azure Compute Gallery image, that application must have been granted an [Azure built-in role](../role-based-access-control/rbac-and-directory-admin-roles.md#azure-roles) that gives it access to the the Shared Image. You can grant this access in the Azure portal by navigating to the Shared Image, selecting **Access control (IAM)** and adding a role assignment for the application.

-> If a request to the the origin timeout, the value for HttpStatusCode is set to **0**.

- [](images/tutorial-aad-outage-basics.png#lightbox)

- [](images/tutorial-aad-outage-permissions.png#lightbox)

-This article includes sample [Azure Policy](../governance/policy/overview.md) definitions that create [targets and capabilities](chaos-studio-targets-capabilities.md) for a specific resource type. You can automatically add resources to Azure Chaos Studio. First, you [deploy these samples as custom policy definitions](../governance/policy/tutorials/create-custom-policy-definition.md). Then you [assign the policy](../governance/policy/assign-policy-portal.md) to a scope.

-To resolve this problem, go to the VM or virtual machine scale set in the Azure portal and go to **Identity**. Open the **User assigned** tab and add your user-assigned identity to the VM. After you're finished, you might need to reboot the VM for the agent to connect.

-These samples cover various ways to to create a new Azure Cloud Service (extended support) deployment.

-For common issues and and workarounds, see [Azure Cloud Services troubleshooting documentation](/troubleshoot/azure/cloud-services/welcome-cloud-services) and [Frequently asked questions](faq.yml)

-| Remote disk disconnected | We're sorry, your virtual machine is unavailable because because of connectivity loss to the remote disk. We're working to reestablish disk connectivity. No additional action is required from you at this time |

-description: Identifies the parts of your Bing Autosuggest application that you need to update to use version 7.

-# Autosuggest API upgrade guide

-This upgrade guide identifies the changes between version 5 and version 7 of the Bing Autosuggest API. Use this guide to help update your application to use version 7.

-## Breaking changes

-### Endpoints

-### Error response objects and error codes

- - `subCode`&mdash;Partitions the error code into discrete buckets, if possible

- - `moreDetails`&mdash;Additional information about the error described in the `message` field

-|Code|SubCode|Description

-|-|-|-

-|ServerError|UnexpectedError<br/>ResourceError<br/>NotImplemented|Bing returns ServerError whenever any of the sub-code conditions occur. The response includes these errors if the HTTP status code is 500.

-|InvalidRequest|ParameterMissing<br/>ParameterInvalidValue<br/>HttpNotAllowed<br/>Blocked|Bing returns InvalidRequest whenever any part of the request is not valid. For example, a required parameter is missing or a parameter value is not valid.<br/><br/>If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400.<br/><br/>If the error is HttpNotAllowed, the HTTP status code is 410.

-|RateLimitExceeded||Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.<br/><br/>Bing returns HTTP status code 429 if you exceeded QPS and 403 if you exceeded QPM.

-|InvalidAuthorization|AuthorizationMissing<br/>AuthorizationRedundancy|Bing returns InvalidAuthorization when Bing cannot authenticate the caller. For example, the `Ocp-Apim-Subscription-Key` header is missing or the subscription key is not valid.<br/><br/>Redundancy occurs if you specify more than one authentication method.<br/><br/>If the error is InvalidAuthorization, the HTTP status code is 401.

-|InsufficientAuthorization|AuthorizationDisabled<br/>AuthorizationExpired|Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. This can occur if the subscription key has been disabled or has expired. <br/><br/>If the error is InsufficientAuthorization, the HTTP status code is 403.

-|Version 5 code|Version 7 code.subCode

-|-|-

-|RequestParameterMissing|InvalidRequest.ParameterMissing

-RequestParameterInvalidValue|InvalidRequest.ParameterInvalidValue

-ResourceAccessDenied|InsufficientAuthorization

-ExceededVolume|RateLimitExceeded

-ExceededQpsLimit|RateLimitExceeded

-Disabled|InsufficientAuthorization.AuthorizationDisabled

-UnexpectedError|ServerError.UnexpectedError

-DataSourceErrors|ServerError.ResourceError

-AuthorizationMissing|InvalidAuthorization.AuthorizationMissing

-HttpNotAllowed|InvalidRequest.HttpNotAllowed

-UserAgentMissing|InvalidRequest.ParameterMissing

-NotImplemented|ServerError.NotImplemented

-InvalidAuthorization|InvalidAuthorization

-InvalidAuthorizationMethod|InvalidAuthorization

-MultipleAuthorizationMethod|InvalidAuthorization.AuthorizationRedundancy

-ExpiredAuthorizationToken|InsufficientAuthorization.AuthorizationExpired

-InsufficientScope|InsufficientAuthorization

-Blocked|InvalidRequest.Blocked

-## Next steps

-> [!div class="nextstepaction"]

-> [Use and display requirements](../bing-web-search/use-display-requirements.md)

-description: This article discusses the concept of suggesting query terms using the Bing Autosuggest API and the impact of query length on relevance.

-# Suggesting query terms

-Typically, you'd call the Bing Autosuggest API each time a user types a new character in your application's search box. The completeness of the query string impacts the relevance of the suggested query terms that the API returns. The more complete the query string, the more relevant the list of suggested query terms are. For example, the suggestions that the API may return for `s` are likely to be less relevant than the queries it returns for `sailing dinghies`.

-## Example request

-The following example shows a request that returns the suggested query strings for *sail*. Remember to URL encode the user's partial query term when you set the [q](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#query) query parameter. For example, if the user entered *sailing les*, set `q` to `sailing+les` or `sailing%20les`.

-```http

-GET https://api.cognitive.microsoft.com/bing/v7.0/suggestions?q=sail&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-The following response contains a list of [SearchAction](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#searchaction) objects that contain the suggested query terms.

-```json

-{

- "url" : "https:\/\/www.bing.com\/search?q=sailing+lessons+seattle&FORM=USBAPI",

- "displayText" : "sailing lessons seattle",

- "query" : "sailing lessons seattle",

- "searchKind" : "WebSearch"

-}, ...

-```

-## Using suggested query terms

-Each suggestion includes a `displayText`, `query` and, `url` field. The `displayText` field contains the suggested query that you use to populate your search box's drop-down list. You must display all suggestions that the response includes, and in the given order.

-The following example shows a drop-down search box with suggested query terms from the Bing Autosuggest API.

-

-If the user selects a suggested query from the drop-down list, you'd use the query term in the `query` field to call the [Bing Web Search API](../../bing-web-search/overview.md) and display the results yourself. Or, you could use the URL in the `url` field to send the user to the Bing search results page instead.

-## Next steps

-* [What is the Bing Autosuggest API?](../get-suggested-search-terms.md)

-description: The Bing Autosuggest API returns a list of suggested queries based on the partial query string in the search box. Learn more about sending requests.

-# Sending requests to the Bing Autosuggest API.

-If your application sends queries to any of the Bing Search APIs, you can use the Bing Autosuggest API to improve your users' search experience. The Bing Autosuggest API returns a list of suggested queries based on the partial query string in the search box. As characters are entered into a search box in your application, you can display suggestions in a drop-down list. Use this article to learn more about sending requests to this API.

-## Bing Autosuggest API Endpoint

-The **Bing Autosuggest API** includes one endpoint, which returns a list of suggested queries from a partial search term.

-To get suggested queries using the Bing API, send a `GET` request to the following endpoint. Use the headers and URL parameters to define further specifications.

-**Endpoint:** Returns search suggestions as JSON results that are relevant to the user's input defined by `?q=""`.

-```http

-GET https://api.cognitive.microsoft.com/bing/v7.0/Suggestions

-```

-For details about headers, parameters, market codes, response objects, errors, etc., see the [Bing Autosuggest API v7](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference) reference.

-The **Bing** APIs support search actions that return results according to their type. All search endpoints return results as JSON response objects.

-All endpoints support queries that return a specific language and/or location by longitude, latitude, and search radius.

-For complete information about the parameters supported by each endpoint, see the reference pages for each type.

-For examples of basic requests using the Autosuggest API, see [Autosuggest Quickstarts](/azure/cognitive-services/bing-autosuggest/get-suggested-search-terms).

-## Bing Autosuggest API requests

-> [!NOTE]

-> * Requests to the Bing Autosuggest API must use the HTTPS protocol.

-We recommend that all requests originate from a server. Distributing the key as part of a client application provides more opportunity malicious third-party access. Additionally, making calls from a server provides a single upgrade point for future updates.

-The request must specify the [q](/rest/api/cognitiveservices/bing-autosuggest-api-v5-reference#query) query parameter, which contains the user's partial search term. Although it's optional, the request should also specify the [mkt](/rest/api/cognitiveservices/bing-autosuggest-api-v5-reference#mkt) query parameter, which identifies the market where you want the results to come from. For a list of optional query parameters, see [Query Parameters](/rest/api/cognitiveservices/bing-autosuggest-api-v5-reference#query-parameters). All query parameter values must be URL encoded.

-The request must specify the [Ocp-Apim-Subscription-Key](/rest/api/cognitiveservices/bing-autosuggest-api-v5-reference#subscriptionkey) header. Although optional, you are encouraged to also specify the following headers:

-The client IP and location headers are important for returning location aware content.

-For a list of all request and response headers, see [Headers](/rest/api/cognitiveservices/bing-autosuggest-api-v5-reference#headers).

-> [!NOTE]

-> When you call the Bing Autosuggest API from JavaScript, your browser's built-in security features might prevent you from accessing the values of these headers.

-To resolve this, you can make the Bing Autosuggest API request through a CORS proxy. The response from such a proxy has a `Access-Control-Expose-Headers` header that filter response headers and makes them available to JavaScript.

-It's easy to install a CORS proxy to allow our [tutorial app](../tutorials/autosuggest.md) to access the optional client headers. First, if you don't already have it, [install Node.js](https://nodejs.org/en/download/). Then enter the following command at a command prompt.

-```console

-npm install -g cors-proxy-server

-```

-Next, change the Bing Autosuggest API endpoint in the HTML file to:

-```http

-http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/Suggestions

-```

-Finally, start the CORS proxy with the following command:

-```console

-cors-proxy-server

-```

-Leave the command window open while you use the tutorial app; closing the window stops the proxy. In the expandable HTTP Headers section below the search results, you can now see the `X-MSEdge-ClientID` header (among others) and verify that it is the same for each request.

-Requests should include all suggested query parameters and headers.

-The following example shows a request that returns the suggested query strings for *sail*.

-> ```http

-> GET https://api.cognitive.microsoft.com/bing/v7.0/suggestions?q=sail&mkt=en-us HTTP/1.1

-> Ocp-Apim-Subscription-Key: 123456789ABCDE

-> X-MSEdge-ClientIP: 999.999.999.999

-> X-Search-Location: lat:47.60357;long:-122.3295;re:100

-> X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-> Host: api.cognitive.microsoft.com

-> ```

-If it's your first time calling any of the Bing APIs, don't include the client ID header. Only include the client ID header if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

-The following web suggestion group is a response to the above request. The group contains a list of search query suggestions, with each suggestion including a `displayText`, `query`, and `url` field.

-The `displayText` field contains the suggested query that you'd use to populate your search box's drop-down list. You must display all suggestions that the response includes, and in the given order.

-If the user selects a query from the drop-down list, you can use it to call the one of the [Bing Search APIs](../../bing-web-search/bing-api-comparison.md?bc=%2fen-us%2fazure%2fbread%2ftoc.json&toc=%2fen-us%2fazure%2fcognitive-services%2fbing-autosuggest%2ftoc.json) and display the results yourself, or send the user to the Bing results page using the returned `url` field.

-```json

-BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC

-X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869

-BingAPIs-Market: en-US

-{

- "_type" : "Suggestions",

- "queryContext" : {

- "originalQuery" : "sail"

- },

- "suggestionGroups" : [{

- "name" : "Web",

- "searchSuggestions" : [{

- "url" : "https:\/\/www.bing.com\/search?q=sailing+lessons+seattle&FORM=USBAPI",

- "displayText" : "sailing lessons seattle",

- "query" : "sailing lessons seattle",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailor+moon+news&FORM=USBAPI",

- "displayText" : "sailor moon news",

- "query" : "sailor moon news",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailor+jack%27s+lincoln+city&FORM=USBAPI",

- "displayText" : "sailor jack's lincoln city",

- "query" : "sailor jack's lincoln city",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailing+anarchy&FORM=USBAPI",

- "displayText" : "sailing anarchy",

- "query" : "sailing anarchy",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailboats+for+sale&FORM=USBAPI",

- "displayText" : "sailboats for sale",

- "query" : "sailboats for sale",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailstn.mylabsplus.com&FORM=USBAPI",

- "displayText" : "sailstn.mylabsplus.com",

- "query" : "sailstn.mylabsplus.com",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailusfood&FORM=USBAPI",

- "displayText" : "sailusfood",

- "query" : "sailusfood",

- "searchKind" : "WebSearch"

- },

- {

- "url" : "https:\/\/www.bing.com\/search?q=sailboats+for+sale+seattle&FORM=USBAPI",

- "displayText" : "sailboats for sale seattle",

- "query" : "sailboats for sale seattle",

- "searchKind" : "WebSearch"

- }]

- }]

-}

-```

-## Next steps

-description: The Bing Autosuggest API returns a list of suggested queries based on the partial query string in the search box.

-# What is Bing Autosuggest?

-If your application sends queries to any of the Bing Search APIs, you can use the Bing Autosuggest API to improve your users' search experience. The Bing Autosuggest API returns a list of suggested queries based on the partial query string in the search box. As characters are entered into the search box, you can display suggestions in a drop-down list.

-## Bing Autosuggest API features

-| Feature | Description |

-|--||

-| [Suggest search terms in real-time](concepts/get-suggestions.md) | Improve your app experience by using the Autosuggest API to display suggested search terms as they're typed. |

-## Workflow

-The Bing Autosuggest API is a RESTful web service, easy to call from any programming language that can make HTTP requests and parse JSON.

-1. Create an [Azure AI services API account](../cognitive-services-apis-create-account.md) with access to the Bing Search APIs. If you don't have an Azure subscription, you can [create an account](https://azure.microsoft.com/free/cognitive-services/) for free.

-2. Send a request to this API each time a user types a new character in your application's search box.

-3. Process the API response by parsing the returned JSON message.

-Typically, you'd call this API each time the user types a new character in your application's search box. As more characters are entered, the API will return more relevant suggested search queries. For example, the suggestions the API might return for a single `s` are likely to be less relevant than ones for `sail`.

-The following example shows a drop-down search box with suggested query terms from the Bing Autosuggest API.

-

-When a user selects a suggestion from the drop-down list, you can use it to begin searching with one of the Bing Search APIs, or directly go to the Bing search results page.

-## Next steps

-To get started quickly with your first request, see [Making Your First Query](quickstarts/csharp.md).

-Familiarize yourself with the [Bing Autosuggest API v7](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference) reference. The reference contains the list of endpoints, headers, and query parameters that you'd use to request suggested query terms, and the definitions of the response objects.

-Visit the [Bing Search API hub page](../bing-web-search/overview.md) to explore the other available APIs.

-Learn how to search the web by using the [Bing Web Search API](../bing-web-search/overview.md), and explore the other [Bing Search APIs](../bing-web-search/index.yml).

-Be sure to read [Bing Use and Display Requirements](../bing-web-search/use-display-requirements.md) so you don't break any of the rules about using the search results.

-description: A list of supported languages and regions for the Bing Autosuggest API.

-# Language and region support for the Bing Autosuggest API

-The following lists the languages supported by Bing Autosuggest API.

-| Language | Language code |

-|:-- |:-:|

-| Arabic | `ar` |

-| Chinese (People's Republic of China) | `zh-CN` |

-| Chinese (Hong Kong SAR) | `zh-HK` |

-| Chinese (Taiwan) | `zh-TW` |

-| Danish | `da` |

-| Dutch (Belgium) | `nl-BE` |

-| Dutch (Netherlands) | `nl-NL` |

-| English (Australia) | `en-AU` |

-| English (Canada) | `en-CA` |

-| English (India) | `en-IN` |

-| English (Indonesia) | `en-ID` |

-| English (Malaysia) | `en-MY` |

-| English (New Zealand) | `en-NZ` |

-| English (Philippines) | `en-PH` |

-| English (South Africa) | `en-ZA` |

-| English (United Kingdom) | `en-GB` |

-| English (United States) | `en-US` |

-| Finnish | `fi` |

-| French (Belgium) | `fr-BE` |

-| French (Canada) | `fr-CA` |

-| French (France) | `fr-FR` |

-| French (Switzerland) | `fr-CH` |

-| German (Austria) | `de-AT` |

-| German (Germany) | `de-DE` |

-| German (Switzerland) | `de-CH` |

-| Italian | `it` |

-| Japanese | `ja` |

-| Korean | `ko` |

-| Norwegian | `no` |

-| Polish | `pl` |

-| Portuguese (Brazil) | `pt-BR`|

-| Portuguese (Portugal) | `pt-PT`|

-| Russian | `ru` |

-| Spanish (Argentina) | `es-AR` |

-| Spanish (Chile) | `es-CL` |

-| Spanish (Mexico) | `es-MX` |

-| Spanish (Spain) | `es-ES` |

-| Spanish (United States) | `es-US` |

-| Swedish | `sv` |

-| Turkish | `tr` |

-## See also

-description: The Autosuggest API offers client libraries that makes it easy to integrate search capabilities into your applications. Use this quickstart to start sending search requests, and get back results.

-zone_pivot_groups: programming-languages-set-fifteen

-# Quickstart: Use the Bing Autosuggest client library

-description: "Learn how to quickly start suggesting search terms in real time with the Bing Autosuggest API and C#."

-# Quickstart: Suggest search queries with the Bing Autosuggest REST API and C#

-Follow this quickstart to learn how to make calls to the Bing Autosuggest API and read the JSON response. This simple C# application sends a partial search query to the API, and returns suggestions for searches. While this application is written in C#, the API is a RESTful Web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/dotnet/Search/BingAutosuggestv7.cs).

-## Prerequisites

-* Any edition of [Visual Studio 2017 or later](https://www.visualstudio.com/downloads/).

-* If you're using Linux/MacOS, this application can be run using [Mono](https://www.mono-project.com/).

-## Create a Visual Search Solution

-1. Create a new console solution in Visual Studio. Then, add the following namespaces into the main code file.

- ```csharp

- using System;

- using System.Collections.Generic;

- using System.Net.Http;

- using System.Net.Http.Headers;

- using System.Text;

- ```

-2. In a new class, create variables for your API host and path, [market code](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#market-codes), and a partial search query. Use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```csharp

- static string host = "https://api.cognitive.microsoft.com";

- static string path = "/bing/v7.0/Suggestions";

- static string market = "en-US";

- static string key = "your-api-key";

-

- static string query = "sail";

- ```

-## Create and send an API request

-1. Create a function called `Autosuggest()` to send a request to the API. Create a new `HttpClient()`, and add your subscription key to the `Ocp-Apim-Subscription-Key` header.

- ```csharp

- async static void Autosuggest()

- {

- HttpClient client = new HttpClient();

- client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

- //..

- }

- ```

-2. In the same function above, create a request URI by combining your API host and path. Append your market to the `mkt=` parameter, and your query to the `query=` parameter. Be sure to URL-encode your query.

- ```csharp

- string uri = host + path + "?mkt=" + market + "&query=" + System.Net.WebUtility.UrlEncode (query);

- ```

-3. Send the request to the uri constructed above, and print the response.

- ```csharp

- HttpResponseMessage response = await client.GetAsync(uri);

- string contentString = await response.Content.ReadAsStringAsync();

- Console.WriteLine(contentString);

- ```

-4. In the main method of your program, call `Autosuggest()`.

- ```csharp

- static void Main(string[] args)

- {

- Autosuggest();

- Console.ReadLine();

- }

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dgvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI\u0026p\u003dDevEx,5003.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dBTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5004.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dc0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI\u0026p\u003dDevEx,5005.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dmnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI\u0026p\u003dDevEx,5006.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dWLFO-B1GG5qtBGnoU1Bizz02YKkg5fgAQtHwhXn4z8I\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5007.1",

- "displayText": "sailpoint",

- "query": "sailpoint",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dquBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI\u0026p\u003dDevEx,5008.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003d0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI\u0026p\u003dDevEx,5009.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003deSSt0MRSbl2V0RFPSuVd-gC7fGOT4717pz55EBUgPec\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2b2025%26FORM%3dUSBAPI\u0026p\u003dDevEx,5010.1",

- "displayText": "sailor 2025",

- "query": "sailor 2025",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Bing Autosuggest tutorial](../tutorials/autosuggest.md)

-## See also

-description: Learn how to quickly start suggesting search terms in real time with the Bing Autosuggest API and Java.

-# Quickstart: Suggest search queries with the Bing Autosuggest REST API and Java

-Follow this quickstart to learn how to make calls to the Bing Autosuggest API and read the JSON response. This simple Java application sends a partial search query to the API, and returns suggestions for searches. While this application is written in Java, the API is a RESTful Web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/java/Search/BingAutosuggestv7.java)

-## Prerequisites

-* The [Java Development Kit(JDK)](https://www.oracle.com/technetwork/java/javase/downloads/)

-* The [Gson library](https://github.com/google/gson)

-## Create and initialize a project

-1. Create a new Java project in your favorite IDE or editor, and import the following libraries.

- ```java

- import java.io.*;

- import java.net.*;

- import java.util.*;

- import javax.net.ssl.HttpsURLConnection;

- import com.google.gson.Gson;

- import com.google.gson.GsonBuilder;

- import com.google.gson.JsonObject;

- import com.google.gson.JsonParser;

- ```

-2. Create variables for your subscription key, the API host and path, your [market code](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#market-codes), and a search query. Use the global endpoint below, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

-

- ```java

- static String subscriptionKey = "enter key here";

- static String host = "https://api.cognitive.microsoft.com";

- static String path = "/bing/v7.0/Suggestions";

- static String mkt = "en-US";

- static String query = "sail";

- ```

-## Format the response

-Create a method named `prettify()` to format the response returned from the Bing Video API. Use the Gson library's `JsonParser` to take in a JSON string and convert it into an object. Then, use `GsonBuilder()` and `toJson()` to create the formatted string.

-```java

-// pretty-printer for JSON; uses GSON parser to parse and re-serialize

-public static String prettify(String json_text) {

- JsonParser parser = new JsonParser();

- JsonObject json = parser.parse(json_text).getAsJsonObject();

- Gson gson = new GsonBuilder().setPrettyPrinting().create();

- return gson.toJson(json);

-}

-```

-## Construct and send the search request

-1. Create a new method named `get_suggestions()` and perform the following steps:

- 1. Construct the URL for your request by combining your API host, path, and encoding your search query. Be sure to url-encode the query before appending it. Create a parameters string for your query by appending the market code to the `mkt=` parameter, and your query to the `q=` parameter.

-

- ```java

-

- public static String get_suggestions () throws Exception {

- String encoded_query = URLEncoder.encode (query, "UTF-8");

- String params = "?mkt=" + mkt + "&q=" + encoded_query;

- //...

- }

- ```

-

- 2. Create a new URL for the request with the API host, path, and parameters that you created in the previous step.

-

- ```java

- //...

- URL url = new URL (host + path + params);

- //...

- ```

-

- 3. Create a `HttpsURLConnection` object, and use `openConnection()` to create a connection. Set the request method to `GET`, and add your subscription key to the `Ocp-Apim-Subscription-Key` header.

- ```java

- //...

- HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();

- connection.setRequestMethod("GET");

- connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);

- connection.setDoOutput(true);

- //...

- ```

- 4. Store the API response in `StringBuilder`. After the response has been captured, close the `InputStreamReader` stream, and return the response.

- ```java

- //...

- StringBuilder response = new StringBuilder ();

- BufferedReader in = new BufferedReader(

- new InputStreamReader(connection.getInputStream()));

- String line;

- while ((line = in.readLine()) != null) {

- response.append(line);

- }

- in.close();

-

- return response.toString();

- ```

-2. In the main function of your application, call `get_suggestions()`, and print the response by using `prettify()`.

-

- ```java

- public static void main(String[] args) {

- try {

- String response = get_suggestions ();

- System.out.println (prettify (response));

- }

- catch (Exception e) {

- System.out.println (e);

- }

- }

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dgvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI\u0026p\u003dDevEx,5003.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dBTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5004.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dc0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI\u0026p\u003dDevEx,5005.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dmnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI\u0026p\u003dDevEx,5006.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dWLFO-B1GG5qtBGnoU1Bizz02YKkg5fgAQtHwhXn4z8I\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5007.1",

- "displayText": "sailpoint",

- "query": "sailpoint",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dquBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI\u0026p\u003dDevEx,5008.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003d0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI\u0026p\u003dDevEx,5009.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003deSSt0MRSbl2V0RFPSuVd-gC7fGOT4717pz55EBUgPec\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2b2025%26FORM%3dUSBAPI\u0026p\u003dDevEx,5010.1",

- "displayText": "sailor 2025",

- "query": "sailor 2025",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Create a single-page web app](../tutorials/autosuggest.md)

-description: Learn how to quickly start suggesting search terms in real time with the Bing Autosuggest API and Node.js.

-# Quickstart: Suggest search queries with the Bing Autosuggest REST API and Node.js

-Follow this quickstart to learn how to make calls to the Bing Autosuggest API and read the JSON response. This simple Node.js application sends a partial search query to the API, and returns suggestions for searches. While this application is written in JavaScript, the API is a RESTful Web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/nodejs/Search/BingAutosuggestv7.js)

-## Prerequisites

-* [Node.js 6](https://nodejs.org/en/download/) or later

-## Create a new application

-1. Create a new JavaScript file in your favorite IDE or editor, and set the strictness and https requirements.

-

- ```javascript

- 'use strict';

-

- let https = require ('https');

- ```

-2. Create variables for the API endpoint host and path, your subscription key, [market code](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#market-codes), and a search term. Use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```javascript

- // Replace the subscriptionKey string value with your valid subscription key.

- let subscriptionKey = 'enter key here';

-

- let host = 'api.cognitive.microsoft.com';

- let path = '/bing/v7.0/Suggestions';

-

- let mkt = 'en-US';

- let query = 'sail';

- ```

-## Construct the search request and query.

-1. Create a parameters string for your query by appending the market code to the `mkt=` parameter, and your query to the `q=` parameter.

- ```javascript

- let params = '?mkt=' + mkt + '&q=' + query;

- ```

-2. Create a function called `get_suggestions()`. Use the variables from the last steps to format a search URL for the API request. Your search term must be URL-encoded before being sent to the API.

- ```javascript

- let get_suggestions = function () {

- let request_params = {

- method : 'GET',

- hostname : host,

- path : path + params,

- headers : {

- 'Ocp-Apim-Subscription-Key' : subscriptionKey,

- }

- };

- //...

- }

- ```

- 1. In the same function, use the request library to send your query to the API. `response_handler` is defined in the next section.

-

- ```javascript

- //...

- let req = https.request(request_params, response_handler);

- req.end();

- ```

-## Create a search handler

-1. Define a function named `response_handler` that takes an HTTP call, `response`, as a parameter.

-Do the following steps within this function:

-

- 1. Define a variable to contain the body of the JSON response.

- ```javascript

- let response_handler = function (response) {

- let body = '';

- };

- ```

- 2. Store the body of the response when the `data` flag is called

-

- ```javascript

- response.on ('data', function (d) {

- body += d;

- });

- ```

- 3. When an `end` flag is signaled, use `JSON.parse()` and `JSON.stringify()` to print the response.

-

- ```javascript

- response.on ('end', function () {

- let body_ = JSON.parse (body);

- let body__ = JSON.stringify (body_, null, ' ');

- console.log (body__);

- });

- response.on ('error', function (e) {

- console.log ('Error: ' + e.message);

- });

- ```

-2. Call `get_suggestions()` to send the request to the Bing Autosuggest API.

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dgvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI\u0026p\u003dDevEx,5003.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dBTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5004.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dc0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI\u0026p\u003dDevEx,5005.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dmnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI\u0026p\u003dDevEx,5006.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dWLFO-B1GG5qtBGnoU1Bizz02YKkg5fgAQtHwhXn4z8I\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5007.1",

- "displayText": "sailpoint",

- "query": "sailpoint",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dquBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI\u0026p\u003dDevEx,5008.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003d0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI\u0026p\u003dDevEx,5009.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003deSSt0MRSbl2V0RFPSuVd-gC7fGOT4717pz55EBUgPec\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2b2025%26FORM%3dUSBAPI\u0026p\u003dDevEx,5010.1",

- "displayText": "sailor 2025",

- "query": "sailor 2025",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Create a single-page web app](../tutorials/autosuggest.md)

-description: Learn how to quickly start suggesting search terms in real time with the Bing Autosuggest API and PHP.

-# Quickstart: Suggest search queries with the Bing Autosuggest REST API and PHP

-Follow this quickstart to learn how to make calls to the Bing Autosuggest API and read the JSON response. This simple PHP application sends a partial search query to the API, and returns suggestions for searches. While this application is written in PHP, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* [PHP 5.6.x](https://php.net/downloads.php) or later

-## Get Autosuggest results

-1. Create a new PHP project in your favorite IDE.

-2. Add the code provided below.

-3. Replace the `subscriptionKey` value with an access key that's valid for your subscription.

-4. Use the global endpoint in the code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

-5. Run the program.

-```php

-<?php

-// NOTE: Be sure to uncomment the following line in your php.ini file.

-// ;extension=php_openssl.dll

-// **********************************************

-// *** Update or verify the following values. ***

-// **********************************************

-// Replace the subscriptionKey string value with your valid subscription key.

-$subscriptionKey = 'enter key here';

-$host = "https://api.cognitive.microsoft.com";

-$path = "/bing/v7.0/Suggestions";

-$mkt = "en-US";

-$query = "sail";

-function get_suggestions ($host, $path, $key, $mkt, $query) {

- $params = '?mkt=' . $mkt . '&q=' . $query;

- $headers = "Content-type: text/json\r\n" .

- "Ocp-Apim-Subscription-Key: $key\r\n";

- // NOTE: Use the key 'http' even if you are making an HTTPS request. See:

- // https://php.net/manual/en/function.stream-context-create.php

- $options = array (

- 'http' => array (

- 'header' => $headers,

- 'method' => 'GET'

- )

- );

- $context = stream_context_create ($options);

- $result = file_get_contents ($host . $path . $params, false, $context);

- return $result;

-}

-$result = get_suggestions ($host, $path, $subscriptionKey, $mkt, $query);

-echo json_encode (json_decode ($result), JSON_PRETTY_PRINT);

-?>

-```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dgvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI\u0026p\u003dDevEx,5003.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dBTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5004.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dc0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI\u0026p\u003dDevEx,5005.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dmnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI\u0026p\u003dDevEx,5006.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dWLFO-B1GG5qtBGnoU1Bizz02YKkg5fgAQtHwhXn4z8I\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5007.1",

- "displayText": "sailpoint",

- "query": "sailpoint",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dquBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI\u0026p\u003dDevEx,5008.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003d0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI\u0026p\u003dDevEx,5009.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003deSSt0MRSbl2V0RFPSuVd-gC7fGOT4717pz55EBUgPec\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2b2025%26FORM%3dUSBAPI\u0026p\u003dDevEx,5010.1",

- "displayText": "sailor 2025",

- "query": "sailor 2025",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Bing Autosuggest tutorial](../tutorials/autosuggest.md)

-## See also

-description: Learn how to quickly start suggesting search terms in real time with the Bing Autosuggest API and Python.

-# Quickstart: Suggest search queries with the Bing Autosuggest REST API and Python

-Follow this quickstart to learn how to make calls to the Bing Autosuggest API and read the JSON response. This simple Python application sends a partial search query to the API, and returns suggestions for searches. While this application is written in Python, the API is a RESTful Web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/python/Search/BingAutosuggestv7.py)

-## Prerequisites

-* [Python 3.x](https://www.python.org/downloads/)

-## Create a new application

-1. Create a new Python file in your favorite IDE or editor. Add the following imports:

- ```python

- import http.client, urllib.parse, json

- ```

-2. Create variables for your API host and path, [market code](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#market-codes), and partial search query. Use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```python

- subscriptionKey = 'enter key here'

- host = 'api.cognitive.microsoft.com'

- path = '/bing/v7.0/Suggestions'

- mkt = 'en-US'

- query = 'sail'

- ```

-3. Create a parameters string by appending your market code to the `mkt=` parameter, and appending your query to the `q=` parameter.

- ```python

- params = '?mkt=' + mkt + '&q=' + query

- ```

-## Create and send an API request

-1. Add your subscription key to a `Ocp-Apim-Subscription-Key` header.

-

- ```python

- headers = {'Ocp-Apim-Subscription-Key': subscriptionKey}

- ```

-2. Connect to the API using `HTTPSConnection()`, and send the `GET` request containing your request parameters.

-

- ```python

- conn = http.client.HTTPSConnection(host)

- conn.request ("GET", path + params, None, headers)

- response = conn.getresponse ()

- return response.read ()

- ```

-3. Get and print the JSON response.

- ```python

- result = get_suggestions ()

- print (json.dumps(json.loads(result), indent=4))

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dgvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI\u0026p\u003dDevEx,5003.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dBTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5004.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dc0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI\u0026p\u003dDevEx,5005.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dmnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI\u0026p\u003dDevEx,5006.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dWLFO-B1GG5qtBGnoU1Bizz02YKkg5fgAQtHwhXn4z8I\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5007.1",

- "displayText": "sailpoint",

- "query": "sailpoint",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dquBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI\u0026p\u003dDevEx,5008.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003d0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI\u0026p\u003dDevEx,5009.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003deSSt0MRSbl2V0RFPSuVd-gC7fGOT4717pz55EBUgPec\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2b2025%26FORM%3dUSBAPI\u0026p\u003dDevEx,5010.1",

- "displayText": "sailor 2025",

- "query": "sailor 2025",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Create a single-page web app](../tutorials/autosuggest.md)

-## See also

-description: Learn how to quickly start suggesting search terms in real time with the Bing Autosuggest API and Ruby.

-# Quickstart: Suggest search queries with the Bing Autosuggest REST API and Ruby

-Follow this quickstart to learn how to make calls to the Bing Autosuggest API and read the JSON response. This simple Ruby application sends a partial search query to the API, and returns suggestions for searches. While this application is written in Ruby, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* [Ruby 2.4](https://www.ruby-lang.org/en/downloads/) or later.

-## Create a new application

-1. Create a new Ruby file in your favorite IDE or editor. Add the following requirements:

- ```ruby

- require 'net/https'

- require 'uri'

- require 'json'

- ```

-2. Create variables for your API host and path, [market code](/rest/api/cognitiveservices-bingsearch/bing-autosuggest-api-v7-reference#market-codes), and partial search query. Use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```ruby

- subscriptionKey = 'enter your key here'

- host = 'https://api.cognitive.microsoft.com'

- path = '/bing/v7.0/Suggestions'

- mkt = 'en-US'

- query = 'sail'

- ```

-3. Create a parameters string by appending your market code to the `mkt=` parameter, and appending your query to the `q=` parameter. Then, construct your request URI by combining the API host, path, and the parameters string.

- ```ruby

- params = '?mkt=' + mkt + '&q=' + query

- uri = URI (host + path + params)

- ```

-## Create and send an API request

-1. Create a request with your URI, and add your subscription key to the `Ocp-Apim-Subscription-Key` header.

-

- ```ruby

- request = Net::HTTP::Get.new(uri)

- request['Ocp-Apim-Subscription-Key'] = subscriptionKey

- ```

-2. Send the request, and store the response.

-

- ```ruby

- response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|

- http.request (request)

- end

- ```

-3. Print the JSON response.

-

- ```ruby

- puts JSON::pretty_generate (JSON (response.body))

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dgvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI\u0026p\u003dDevEx,5003.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dBTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5004.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dc0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI\u0026p\u003dDevEx,5005.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dmnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI\u0026p\u003dDevEx,5006.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dWLFO-B1GG5qtBGnoU1Bizz02YKkg5fgAQtHwhXn4z8I\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailpoint%26FORM%3dUSBAPI\u0026p\u003dDevEx,5007.1",

- "displayText": "sailpoint",

- "query": "sailpoint",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003dquBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI\u0026p\u003dDevEx,5008.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003d0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI\u0026p\u003dDevEx,5009.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG\u003d2ACC4FE8B02F4AACB9182A6502B0E556\u0026CID\u003d1D546424A4CB64AF2D386F26A5CD6583\u0026rd\u003d1\u0026h\u003deSSt0MRSbl2V0RFPSuVd-gC7fGOT4717pz55EBUgPec\u0026v\u003d1\u0026r\u003dhttps%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2b2025%26FORM%3dUSBAPI\u0026p\u003dDevEx,5010.1",

- "displayText": "sailor 2025",

- "query": "sailor 2025",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Create a single-page web app](../tutorials/autosuggest.md)

-## See also

-description: In this tutorial, you will build a web page that allows users to query the Bing Autosuggest API and displays the query results.

-# Tutorial: Get search suggestions on a web page

-In this tutorial, we'll build a Web page that allows users to query the Bing Autosuggest API.

-This tutorial shows you how to:

-> [!div class="checklist"]

-> - Make a simple query to the Bing Autosuggest API

-> - Display query results

-## Prerequisites

-To follow along with the tutorial, you need a subscription key for the Bing Autosuggest API. If you don't have one, [create a Bing Autosuggest resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesBingAutosuggest-v7) in the Azure portal.

-## Create a new Web page

-Open a text editor. Create a new file named, for example, autosuggest.html.

-## HTML header

-Add the HTML header information and begin the script section as follows.

-```html

-<!DOCTYPE html>

-<html>

-<head>

- <meta charset="UTF-8">

- <title>Bing Autosuggest</title>

-<style type="text/css">

- html, body, div, p, h1, h2 {font-family: Verdana, "Lucida Sans", sans-serif;}

- html, body, div, p {font-weight: normal;}

- h1, h2 {font-weight: bold;}

- sup {font-weight: normal;}

- html, body, div, p {font-size: 12px;}

- h1 {font-size: 20px;}

- h2 {font-size: 16px;}

- h1, h2 {clear: left;}

- img#logo {float: right;

-</style>

-<script type="text/javascript">

-```

-## getSubscriptionKey function

-The getSubscriptionKey function returns the Bing Autosuggest API key. It either retrieves it from

-local storage (that is, a cookie) or prompts the user for if needed.

-Begin the getSubscriptionKey function and declare the cookie name as follows.

-```html

-getSubscriptionKey = function() {

- var COOKIE = "bing-autosuggest-api-key"; // name used to store API key in key/value storage

-```

-The findCookie helper function returns the value of the specified cookie; if the cookie is not

-found, it returns an empty string.

-```html

- function findCookie(name) {

- var cookies = document.cookie.split(";");

- for (var i = 0; i < cookies.length; i++) {

- var keyvalue = cookies[i].split("=");

- if (keyvalue[0].trim() === name) {

- return keyvalue[1];

- }

- }

- return "";

- }

-```

-The getSubscriptionKeyCookie helper function prompts the user for the value of the Bing

-Autosuggest API key, and returns the key value.

-```html

- function getSubscriptionKeyCookie() {

- var key = findCookie(COOKIE);

- while (key.length !== 32) {

- key = prompt("Enter Bing Autosuggest API subscription key:", "").trim();

- var expiry = new Date();

- expiry.setFullYear(expiry.getFullYear() + 2);

- document.cookie = COOKIE + "=" + key.trim() + "; expires=" + expiry.toUTCString();

- }

- return key;

- }

-```

-The getSubscriptionKeyLocalStorage helper function first tries to retrieve the Bing Autosuggest

-API key by looking up the appropriate cookie. If the cookie is not found, it prompts the user for

-the key value. It then returns the key value.

-```html

- function getSubscriptionKeyLocalStorage() {

- var key = localStorage.getItem(COOKIE) || "";

- while (key.length !== 32)

- key = prompt("Enter Bing Autosuggest API subscription key:", "").trim();

- localStorage.setItem(COOKIE, key)

- return key;

- }

-```

-The getSubscriptionKey helper function takes one parameter, **invalidate**. If **invalidate** is

-**true**, getSubscriptionKey deletes the cookie that contains the Bing Autosuggest API key. If

-**invalidate** is **false**, getSubscriptionKey returns the value of the Bing Autosuggest API key.

-```html

- function getSubscriptionKey(invalidate) {

- if (invalidate) {

- try {

- localStorage.removeItem(COOKIE);

- } catch (e) {

- document.cookie = COOKIE + "=";

- }

- } else {

- try {

- return getSubscriptionKeyLocalStorage();

- } catch (e) {

- return getSubscriptionKeyCookie();

- }

- }

- }

-```

-Return the getSubscriptionKey helper function as the result of the outer getSubscriptionKey

-function. Close the definition of the outer getSubscriptionKey function.

-```html

- return getSubscriptionKey;

-}();

-```

-## Helper functions

-The pre helper function returns the specified text preformatted with the [pre](https://www.w3schools.com/tags/tag_pre.asp)

-HTML tag.

-```html

-function pre(text) {

- return "<pre>" + text.replace(/&/g, "&amp;").replace(/</g, "&lt;") + "</pre>"

-}

-```

-The renderSearchResults function displays the specified results from the Bing Autosuggest API, using JSON pretty printing.

-```html

-function renderSearchResults(results) {

- document.getElementById("results").innerHTML = pre(JSON.stringify(results, null, 2));

-}

-```

-The renderErrorMessage function displays the specified error message and error code.

-```html

-function renderErrorMessage(message, code) {

- if (code)

- document.getElementById("results").innerHTML = "<pre>Status " + code + ": " + message + "</pre>";

- else

- document.getElementById("results").innerHTML = "<pre>" + message + "</pre>";

-}

-```

-## bingAutosuggest function

-The bingAutosuggest function is called each time the user enters text in the HTML form field.

-It takes two parameters: the contents of the HTML form field, and the Bing Autosuggest API key.

-```html

-function bingAutosuggest(query, key) {

-```

-Specify the Bing Autosuggest API endpoint and declare an XMLHttpRequest object, which we will

-use to send requests. You can use the global endpoint below, or the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

-```html

- var endpoint = "https://api.cognitive.microsoft.com/bing/v7.0/Suggestions";

- var request = new XMLHttpRequest();

- try {

- request.open("GET", endpoint + "?q=" + encodeURIComponent(query));

- }

- catch (e) {

- renderErrorMessage("Bad request");

- return false;

- }

-```

-Set the **Ocp-Apim-Subscription-Key** header to the value of the Bing Autosuggest API key.

-```html

- request.setRequestHeader("Ocp-Apim-Subscription-Key", key);

-```

-Handle the response from the endpoint. If the status is 200 (OK), display the results; otherwise,

-display the error information.

-```html

- request.addEventListener("load", function() {

- if (this.status === 200) {

- renderSearchResults(JSON.parse(this.responseText));

- }

- else {

- if (this.status === 401) getSubscriptionKey(true);

- renderErrorMessage(this.statusText, this.status);

- }

- });

-```

-Also handle possible error events from the XMLHttpRequest object.

-```html

- request.addEventListener("error", function() {

- renderErrorMessage("Network error");

- });

- request.addEventListener("abort", function() {

- renderErrorMessage("Request aborted");

- });

-```

-Send the request. Close the bingAutosuggest function, the **script** tag, and the **head** tag.

-```html

- request.send();

- return false;

-}

-// --></script>

-</head>

-```

-## HTML body

-When the Web page loads, make sure we have the Bing Autosuggest API key, prompting the user for it if needed.

-```html

-<body onload="document.forms.bing.query.focus(); getSubscriptionKey();">

-```

-Display the Bing logo.

-```html

-<img id="logo" align=base src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAAyCAIAAAAYxYiPAAAAA3NCSVQICAjb4U/gAAARMElEQVR42u2bCVRUV5rHi8VxaeNuOumYTs706aTTZrp7TqbTk5g+9kn3OZN0pjudpZM5SfdJzEzPyZmO1gbIJhmNmijy6hUFsisCgsqigoCt7IoKgoDgUgXILntR+/aWzHfvfQUFFEURsU8cKe/hFFL16r3f++53/9//uyXSWUwjZgPDshzHcy4PnuMXHvP4EJ1qufpPyRHby3Iv93XqbDY7y7IC9QU48wr6RMtVEb1NpJAvoeQvpVF7L5c0jQ6ZHAwJcH6B+HyBzm6pEymkIlomouUiWiqiJCvpwDdOxCdfr+nV6x0Mwy+gnqeIJqAxa3iikJDhEyX5fmx4eZcGJ+yFxz2DPg6pQwA9eQBuSnJC3bCQPe4/6ChxjqbxAVQgnHM8OKBzW5s4lucfsOSxAHoWPh4eggRy/ubprQzL6a1Wo83KfZuWl5lBU39v0CDeQcDbGQa0PB7jT4RfHawDJD562bTzERiznI1l4xurX0yNfCVdcUbTAtAXQE+PSnbEYgkoyfmkOGNL8dEtxZkwPhFGFjz/tCR7b+35su5WrcXCuq1gOa5ZO7Q6eruIBuEk/WH8zj6LaQH0dNB8t8X03dgIqJ6cQyainENBhmSJQvxi2v4j12tMqIydFN3wy8XuO0sOSNEVUZI1ypA23cgCaDegewTQAlYfGNTEQCWVQkrO1l8h+eu5E2M2m+u5AfRBq+Xf0unFlHSxUv5BQZqRcSyAdg/60dgd+NPFf8hPiaotPQCjpnR/bWnExcI/5h96KmmXHyqsUGbwo+S7Lp2zu0Y0immuR6/NbLqSc7NhxGb59qyGXoMm6/59Bt0rgEYcY+svsOz4IscxHJhdXK/REFRZsISENiX9fkx4q0E3nqnRKxFrbIux5I3fnhL8Rp038o77u2iluxbjo7Fh+HwkqmvVnBt1wVoZ9rPibB8KQCPc6Tfr3cmQb6HX4QH0gW0ENATIHe2gwW5lp4rb+wZaKVE2uAWNgraqp2OJkqRsyb7qc+OgJ+tuMhG5mWS6kGsEhc4730TeJ/zXN1X9bh4zg4bhAlpSfPS149Gqa1U3RgeMdlCraCqji55f0GZIHeEkoqMbqqdXd/j3r2/ptd+JDhQpUbLec6GYnQyaQY46KlsQLpfcgZx2koI4IScRSQ6vtzIM1DhjVovJbnOgtCOkHo+qH+t+JPAdAERvMessZrPdzuBqYNLxcQ3lFWh4Y2mnelmU2EcpWR8T+ubJ5JTmq61jWjPjmF683V/QuLRuHBlcCuKPkvlFSVKba3ERw5HbAJjKutU5rU25msbmgT7X0zE5HPmtzdmaxhx1Y59eR25Jl24sqeHynwozXj2m2pRJv5EXF1p++lJfp4VhZpy1+H/hzzqrtayrNbQ8/628xFcyqV8di34vL2XfxfMtw/1WtEywl3o7cjXXc2431fZ2zgI6D0CjIzN6u+Pl1AOiaCJRpb5Rkqfid/65MCNPfb3PqIeIwPGN/t1X0CwSFmx6S70f0nmyNcqgOu0AClyeJbcB5N4v0ykQLT6UJLAkx/XG95j0j0YH+dAS36itJ243WR3M0VsNG5N2+0fB2itGKzC6amQRr1WGhFadGXWmymmzioPbWdvf87vchOWwTlBEO4iJePc/INkQu2NfXaXWbn8//7Nsr17X0N9T1aWBErSkSwNlt2Z0SG+DpOCm8fJ/b7k8gBQkHh4AAAAASUVORK5CYII=">

-```

-Create an HTML form with a text field. Handle the `oninput` event and call the `bingAutosuggest()`

-function, passing the contents of the text field and the Bing Autosuggest API key.

-```html

-<form name="bing" oninput="return bingAutosuggest(this.query.value, getSubscriptionKey())">

- <h2>Autosuggest</h2>

- <input type="text" name="query" size="80" placeholder="Autosuggest" autocomplete=off>

-</form>

-```

-Add the HTML **div** tag that we use to display the results. The JavaScript we defined

-previously refers to this **div** tag.

-```html

-<h2>Results</h2>

-<div id="results">

-<p>None yet.</p>

-</div>

-</body>

-</html>

-```

-Save the file.

-## Display results

-Open the Web page in your browser. At the prompt, enter your Bing Autosuggest API subscription key. Then enter a query (for example, "sail") in the **Autosuggest** text box. As you type, the Web page automatically updates to display the Autosuggest results.

-```json

-{

- "_type": "Suggestions",

- "queryContext": {

- "originalQuery": "sail"

- },

- "suggestionGroups": [

- {

- "name": "Web",

- "searchSuggestions": [

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=vheQSvKZylM3dlX_B9bQ8-hQEsEJo8zDD2y7H1nsBjE&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2bbrinkley%2bcook%26FORM%3dUSBAPI&p=DevEx,5003.1",

- "displayText": "sailor brinkley cook",

- "query": "sailor brinkley cook",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=EStLqAfxGCa44Ur3jEMXBv-Qp-lXUSFJbkBfnUdKKDg&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailor%2bbrinkley%26FORM%3dUSBAPI&p=DevEx,5004.1",

- "displayText": "sailor brinkley",

- "query": "sailor brinkley",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=gvtP9TS9NwhajSapY2Se6y1eCbP2fq_GiP2n-cxi6OY&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailrite%26FORM%3dUSBAPI&p=DevEx,5005.1",

- "displayText": "sailrite",

- "query": "sailrite",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=c0QOA_j6swCZJy9FxqOwke2KslJE7ZRmMooGClAuCpY&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboats%2bfor%2bsale%26FORM%3dUSBAPI&p=DevEx,5006.1",

- "displayText": "sailboats for sale",

- "query": "sailboats for sale",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=mnMdREUH20SepmHQH1zlh9Hy_w7jpOlZFm3KG2R_BoA&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailing%2banarchy%26FORM%3dUSBAPI&p=DevEx,5007.1",

- "displayText": "sailing anarchy",

- "query": "sailing anarchy",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=0udadFl0gCTKCp0QmzQTXS3_y08iO8FpwsoKPHPS6kw&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailboatdata%26FORM%3dUSBAPI&p=DevEx,5008.1",

- "displayText": "sailboatdata",

- "query": "sailboatdata",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=BTS0G6AakxntIl9rmbDXtk1n6rQpsZZ99aQ7ClE7dTY&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsail%2bsand%2bpoint%26FORM%3dUSBAPI&p=DevEx,5009.1",

- "displayText": "sail sand point",

- "query": "sail sand point",

- "searchKind": "WebSearch"

- },

- {

- "url": "https://www.bing.com/cr?IG=30C49D910FAE478288D54A8DBC5D66F1&CID=122B759B00966D02199C7E9001906C30&rd=1&h=quBMwmKlGwqC5wAU0K7n416plhWcR8zQCi7r-Fw9Y0w&v=1&r=https%3a%2f%2fwww.bing.com%2fsearch%3fq%3dsailflow%26FORM%3dUSBAPI&p=DevEx,5010.1",

- "displayText": "sailflow",

- "query": "sailflow",

- "searchKind": "WebSearch"

- }

- ]

- }

- ]

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Use and display requirements](../../bing-web-search/use-display-requirements.md)

-description: "Use this quickstart to begin requesting search results from your Bing Custom Search instance in C#. "

-# Quickstart: Call your Bing Custom Search endpoint using C#

-Use this quickstart to learn how to request search results from your Bing Custom Search instance. Although this application is written in C#, the Bing Custom Search API is a RESTful web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/dotnet/Search/BingCustomSearchv7.cs).

-## Prerequisites

- To install this package in Visual Studio:

- 1. Right-click your project in **Solution Explorer**, and then select **Manage NuGet Packages**.

- 2. Search for and select *Microsoft.Azure.CognitiveServices.Search.CustomSearch*, and then install the package.

- When you install the Bing Custom Search NuGet package, Visual Studio also installs the following packages:

- - **Microsoft.Rest.ClientRuntime**

- - **Microsoft.Rest.ClientRuntime.Azure**

- - **Newtonsoft.Json**

-## Create and initialize the application

-1. Create a new C# console application in Visual Studio. Then, add the following packages to your project:

- ```csharp

- using System;

- using System.Net.Http;

- using System.Web;

- using Newtonsoft.Json;

- ```

-2. Create the following classes to store the search results returned by the Bing Custom Search API:

- ```csharp

- public class BingCustomSearchResponse {

- public string _type{ get; set; }

- public WebPages webPages { get; set; }

- }

- public class WebPages {

- public string webSearchUrl { get; set; }

- public int totalEstimatedMatches { get; set; }

- public WebPage[] value { get; set; }

- }

- public class WebPage {

- public string name { get; set; }

- public string url { get; set; }

- public string displayUrl { get; set; }

- public string snippet { get; set; }

- public DateTime dateLastCrawled { get; set; }

- public string cachedPageUrl { get; set; }

- }

- ```

-3. In the main method of your project, create the following variables for your Bing Custom Search API subscription key, search instance's custom configuration ID, and search term:

- ```csharp

- var subscriptionKey = "YOUR-SUBSCRIPTION-KEY";

- var customConfigId = "YOUR-CUSTOM-CONFIG-ID";

- var searchTerm = args.Length > 0 ? args[0]:"microsoft";

- ```

-4. Construct the request URL by appending your search term to the `q=` query parameter, and your search instance's custom configuration ID to the `customconfig=` parameter. Separate the parameters with an ampersand (`&`). For the `url` variable value, you can use the global endpoint in the following code, or use the [custom subdomain](../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```csharp

- var url = "https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/search?" +

- "q=" + searchTerm + "&" +

- "customconfig=" + customConfigId;

- ```

-## Send and receive a search request

-1. Create a request client, and add your subscription key to the `Ocp-Apim-Subscription-Key` header.

- ```csharp

- var client = new HttpClient();

- client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

- ```

-2. Perform the search request and get the response as a JSON object.

- ```csharp

- var httpResponseMessage = client.GetAsync(url).Result;

- var responseContent = httpResponseMessage.Content.ReadAsStringAsync().Result;

- BingCustomSearchResponse response = JsonConvert.DeserializeObject<BingCustomSearchResponse>(responseContent);

- ```

-## Process and view the results

- ```csharp

- for(int i = 0; i < response.webPages.value.Length; i++) {

- var webPage = response.webPages.value[i];

-

- Console.WriteLine("name: " + webPage.name);

- Console.WriteLine("url: " + webPage.url);

- Console.WriteLine("displayUrl: " + webPage.displayUrl);

- Console.WriteLine("snippet: " + webPage.snippet);

- Console.WriteLine("dateLastCrawled: " + webPage.dateLastCrawled);

- Console.WriteLine();

- }

- Console.WriteLine("Press any key to exit...");

- Console.ReadKey();

- ```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a Custom Search web app](./tutorials/custom-search-web-page.md)

-description: Use this quickstart to begin requesting search results from your Bing Custom Search instance in Java.

-# Quickstart: Call your Bing Custom Search endpoint using Java

-Use this quickstart to learn how to request search results from your Bing Custom Search instance. Although this application is written in Java, the Bing Custom Search API is a RESTful web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/java/Search/BingCustomSearchv7.java).

-## Prerequisites

-## Create and initialize the application

-1. Create a new Java project in your favorite IDE or editor, and import the following libraries:

- ```java

- import java.io.InputStream;

- import java.net.URL;

- import java.net.URLEncoder;

- import java.util.HashMap;

- import java.util.List;

- import java.util.Map;

- import java.util.Scanner;

- import javax.net.ssl.HttpsURLConnection;

- import com.google.gson.Gson;

- import com.google.gson.GsonBuilder;

- import com.google.gson.JsonObject;

- import com.google.gson.JsonParser;

- ```

-2. Create a class named `CustomSrchJava`, and then create variables for your subscription key, custom search endpoint, and search instance's custom configuration ID. You can use the global endpoint in the following code, or use the [custom subdomain](../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```java

- public class CustomSrchJava {

- static String host = "https://api.cognitive.microsoft.com";

- static String path = "/bingcustomsearch/v7.0/search";

- static String subscriptionKey = "YOUR-SUBSCRIPTION-KEY";

- static String customConfigId = "YOUR-CUSTOM-CONFIG-ID";

- static String searchTerm = "Microsoft";

- ...

- ```

-3. Create another class named `SearchResults` to contain the response from your Bing Custom Search instance.

- ```java

- class SearchResults {

- HashMap<String, String> relevantHeaders;

- String jsonResponse;

- SearchResults(HashMap<String, String> headers, String json) {

- relevantHeaders = headers;

- jsonResponse = json;

- }

- }

- ```

-4. Create a function named `prettify()` to format the JSON response from the Bing Custom Search API.

- ```java

- // pretty-printer for JSON; uses GSON parser to parse and re-serialize

- public static String prettify(String json_text) {

- JsonParser parser = new JsonParser();

- JsonObject json = parser.parse(json_text).getAsJsonObject();

- Gson gson = new GsonBuilder().setPrettyPrinting().create();

- return gson.toJson(json);

- }

- ```

-## Send and receive a search request

-1. Create a function named `SearchWeb()` that sends a request and returns a `SearchResults` object. Create the request url by combining your custom configuration ID, query, and endpoint information. Add your subscription key to the `Ocp-Apim-Subscription-Key` header.

- ```java

- public class CustomSrchJava {

- ...

- public static SearchResults SearchWeb (String searchQuery) throws Exception {

- // construct the URL for your search request (endpoint + query string)

- URL url = new URL(host + path + "?q=" + URLEncoder.encode(searchTerm, "UTF-8") + "&CustomConfig=" + customConfigId);

- HttpsURLConnection connection = (HttpsURLConnection)url.openConnection();

- connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);

- ...

- ```

-2. Create a stream and store the JSON response in a `SearchResults` object.

- ```java

- public class CustomSrchJava {

- ...

- public static SearchResults SearchWeb (String searchQuery) throws Exception {

- ...

- // receive the JSON body

- InputStream stream = connection.getInputStream();

- String response = new Scanner(stream).useDelimiter("\\A").next();

-

- // construct result object for return

- SearchResults results = new SearchResults(new HashMap<String, String>(), response);

-

- stream.close();

- return results;

- }

- ```

-3. Print the JSON response.

- ```java

- System.out.println("\nJSON Response:\n");

- System.out.println(prettify(result.jsonResponse));

- ```

-4. Run the program.

-

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a Custom Search web app](./tutorials/custom-search-web-page.md)

-description: Use this quickstart to begin requesting search results from your Bing Custom Search instance using Node.js.

-# Quickstart: Call your Bing Custom Search endpoint using Node.js

-Use this quickstart to learn how to request search results from your Bing Custom Search instance. Although this application is written in JavaScript, the Bing Custom Search API is a RESTful web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/nodejs/Search/BingCustomSearchv7.js).

-## Prerequisites

-## Create and initialize the application

- ```javascript

- var request = require("request");

-

- var subscriptionKey = 'YOUR-SUBSCRIPTION-KEY';

- var customConfigId = 'YOUR-CUSTOM-CONFIG-ID';

- var searchTerm = 'microsoft';

- ```

-## Send and receive a search request

-1. Create a variable to store the information being sent in your request. Construct the request URL by appending your search term to the `q=` query parameter, and your search instance's custom configuration ID to the `customconfig=` parameter. Separate the parameters with an ampersand (`&`). You can use the global endpoint in the following code, or use the [custom subdomain](../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```javascript

- var info = {

- url: 'https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/search?' +

- 'q=' + searchTerm + "&" +

- 'customconfig=' + customConfigId,

- headers: {

- 'Ocp-Apim-Subscription-Key' : subscriptionKey

- }

- }

- ```

-1. Use the JavaScript request library to send a search request to your Bing Custom Search instance and print information about the results, including its name, url, and the date the webpage was last crawled.

- ```javascript

- request(info, function(error, response, body){

- var searchResponse = JSON.parse(body);

- for(var i = 0; i < searchResponse.webPages.value.length; ++i){

- var webPage = searchResponse.webPages.value[i];

- console.log('name: ' + webPage.name);

- console.log('url: ' + webPage.url);

- console.log('displayUrl: ' + webPage.displayUrl);

- console.log('snippet: ' + webPage.snippet);

- console.log('dateLastCrawled: ' + webPage.dateLastCrawled);

- console.log();

- }

- ```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a Custom Search web app](./tutorials/custom-search-web-page.md)

-description: Use this quickstart to begin requesting search results from your Bing Custom Search instance using Python.

-# Quickstart: Call your Bing Custom Search endpoint using Python

-Use this quickstart to learn how to request search results from your Bing Custom Search instance. Although this application is written in Python, the Bing Custom Search API is a RESTful web service compatible with most programming languages. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/python/Search/BingCustomSearchv7.py).

-## Prerequisites

-## Create and initialize the application

- ```python

- import json

- import requests

-

- subscriptionKey = "YOUR-SUBSCRIPTION-KEY"

- customConfigId = "YOUR-CUSTOM-CONFIG-ID"

- searchTerm = "microsoft"

- ```

-## Send and receive a search request

-1. Construct the request URL by appending your search term to the `q=` query parameter, and your search instance's custom configuration ID to the `customconfig=` parameter. Separate the parameters with an ampersand (`&`). You can use the global endpoint in the following code, or use the [custom subdomain](../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```python

- url = 'https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/search?' + 'q=' + searchTerm + '&' + 'customconfig=' + customConfigId

- ```

-2. Send the request to your Bing Custom Search instance, and print the returned search results.

- ```python

- r = requests.get(url, headers={'Ocp-Apim-Subscription-Key': subscriptionKey})

- print(r.text)

- ```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a Custom Search web app](./tutorials/custom-search-web-page.md)

-description: Custom Autosuggest returns a list of suggested search query strings that are relevant to your search experience.

-# Configure your custom autosuggest experience

-Custom Autosuggest returns a list of suggested search query strings that are relevant to your search experience. The suggested query strings are based on a partial query string that the user provides in the search box. The list will contain a maximum of 10 suggestions.

-You specify whether to return only custom suggestions or to also include Bing suggestions. If you include Bing suggestions, custom suggestions appear before the Bing suggestions. If you provide enough relevant suggestions, it's possible that the returned list of suggestions will not include Bing suggestions. Bing suggestions are always in the context of your Custom Search instance.

-To configure search query suggestions for your instance, click the **Autosuggest** tab.

-> [!NOTE]

-> To use this feature, you must subscribe to Custom Search at the appropriate level (see [pricing](https://azure.microsoft.com/pricing/details/cognitive-services/bing-custom-search/)).

-It can take up to 24 hours for suggestions to be reflected in the serving endpoint (API or hosted UI).

-## Enable Bing suggestions

-To enable Bing suggestions, toggle the **Automatic Bing suggestions** slider to the on position. The slider becomes blue.

-## Add your own suggestions

-To add your own query string suggestions, add them to the list under **User-defined suggestions**. After adding a suggestion in the list, press the enter key or click the **+** icon. You can specify the suggestion in any language. You can add a maximum of 5,000 query string suggestions.

-## Upload suggestions

-As an option, you can upload a list of suggestions from a file. The file must contain one search query string per line. To upload the file, click the upload icon and select the file to upload. The service extracts the suggestions from the file and adds them to the list.

-## Remove suggestions

-To remove a query string suggestion, click the remove icon next to the suggestion you want to remove.

-## Block suggestions

-If you include Bing suggestions, you can add a list of search query strings you don't want Bing to return. To add blocked query strings, click **Show blocked suggestions**. Add the query string to the list and press the enter key or click the **+** icon. You can add a maximum of 50 blocked query strings.

->[!NOTE]

->It may take up to 24 hours for Custom Autosuggest configuration changes to take effect.

-## Enabling Autosuggest in Hosted UI

-To enable query string suggestions for your hosted UI, click **Hosted UI**. Scroll down to the **Additional Configuration** section. Under **Web search**, select **On** for **Enable autosuggest**. To enable Autosuggest, you must select a layout that includes a search box.

-## Calling the Autosuggest API

-To get suggested query strings using the Bing Custom Search API, send a `GET` request to the following endpoint.

-```

-GET https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/Suggestions

-```

-The response contains a list of `SearchAction` objects that contain the suggested query strings.

-```

- {

- "displayText" : "sailing lessons seattle",

- "query" : "sailing lessons seattle",

- "searchKind" : "CustomSearch"

- },

-```

-Each suggestion includes a `displayText` and `query` field. The `displayText` field contains the suggested query string that you use to populate your search box's dropdown list.

-If the user selects a suggested query string from the dropdown list, use the query string in the `query` field when calling the [Bing Custom Search API](overview.md).

-## Next steps

-description: The portal lets you create a search instance that specifies the slices of the web; domains, subpages, and webpages.

-# Configure your Bing Custom Search experience

-A Custom Search instance lets you tailor the search experience to include content only from websites that your users care about. Instead of performing a web-wide search, Bing searches only the slices of the web that interest you. To create your custom view of the web, use the Bing Custom Search [portal](https://www.customsearch.ai).

-The portal lets you create a search instance that specifies the slices of the web: domains, subpages, and webpages, that you want Bing to search, and those that you donΓÇÖt want it to search. The portal can also suggest content that you may want to include.

-Use the following when defining your slices of the web:

-| Slice name | Description |

-|||

-| Domain | A domain slice includes all content found within an internet domain. For example, `www.microsoft.com`. Omitting `www.` causes Bing to also search the domainΓÇÖs subdomains. For example, if you specify `microsoft.com`, Bing also returns results from `support.microsoft.com` or `technet.microsoft.com`. |

-| Subpage | A subpage slice includes all content found in the subpage and paths below it. You may specify a maximum of two subpages in the path. For example, `www.microsoft.com/en-us/windows/` |

-| Webpage | A webpage slice can include only that webpage in a custom search. You can optionally specify whether to include subpages. |

-> [!IMPORTANT]

-> All domains, subpages, and webpages that you specify must be public and indexed by Bing. If you own a public site that you want to include in the search, and Bing hasnΓÇÖt indexed it, see the Bing [webmaster documentation](https://www.bing.com/webmaster/help/webmaster-guidelines-30fba23a) for details about getting Bing to index it. Also, see the webmaster documentation for details about getting Bing to update your crawled site if the index is out of date.

-## Add slices of the web to your custom search instance

-When you create your custom search instance, you can specify the slices of the web: domains, subpages, and webpages, that you want to have included or blocked from your search results.

-If you know the slices you want to include in your custom search instance, add them to your instanceΓÇÖs **Active** list.

-If youΓÇÖre not sure which slices to include, you can send search queries to Bing in the **Preview** pane and select the slices that you want. To do this:

-1. select "Bing" from the dropdown list in the Preview pane, and enter a search query

-2. Click **Add site** next to the result you want to include. Then click OK.

->[!NOTE]

-> [!INCLUDE[publish or revert](./includes/publish-revert.md)]

-<a name="active-and-blocked-lists"></a>

-### Customize your search experience with Active and Blocked lists

-You can access the list of active and blocked slices by clicking on the **Active** and **Blocked** tabs in your custom search instance. Slices added to the active list will be included in your custom search. Blocked slices won't be searched, and won't appear in your search results.

-To specify the slices of the web you want Bing to search, click the **Active** tab and add one or more URLs. To edit or delete URLs, use the options under the **Controls** column.

-When adding URLs to the **Active** list you can add single URLs, or multiple URLs at once by uploading a text file using the upload icon.

-

-To upload a file, create a text file and specify a single domain, subpage, or webpage per line. Your file will be rejected if it isn't formatted correctly.

-> [!NOTE]

-> * You can only upload a file to the **Active** list. You cannot use it to add slices to the **Blocked** list.

-> * If the **Blocked** list contains a domain, subpage, or webpage that you specified in the upload file, it will be removed from the **Blocked** list, and added to the **Active** list.

-> * Duplicate entries in your upload file will be ignored by Bing Custom Search.

-### Get website suggestions for your search experience

-After adding web slices to the **Active** list, the Bing Custom Search portal will generate website and subpage suggestions at the bottom of the tab. These are slices that Bing Custom Search thinks you might want to include. Click **Refresh** to get updated suggestions after updating your custom search instance's settings. This section is only visible if suggestions are available.

-## Search for images and videos

-You can search for images and videos similarly to web content by using the [Bing Custom Image Search API](/rest/api/cognitiveservices-bingsearch/bing-custom-images-api-v7-reference) or the [Bing Custom Video Search API](/rest/api/cognitiveservices-bingsearch/bing-custom-videos-api-v7-reference). You can display these results with the [hosted UI](hosted-ui.md), or the APIs.

-These APIs are similar to the non-custom [Bing Image Search](../bing-image-search/overview.md) and [Bing Video Search](../bing-video-search/overview.md) APIs, but search the entire web, and do not require the `customConfig` query parameter. See these documentation sets for more information on working with images and videos.

-## Test your search instance with the Preview pane

-You can test your search instance by using the preview pane on the portal's right side to submit search queries and view the results.

-1. Below the search box, select **My Instance**. You can compare the results from your search experience to Bing, by selecting **Bing**.

-2. Select a safe search filter and which market to search (see [Query Parameters](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#query-parameters)).

-3. Enter a query and press enter or click the search icon to view the results from the current configuration. You can change your search type you perform by clicking **Web**, **Image**, or **Video** to get corresponding results.

-<a name="adjustrank"></a>

-## Adjust the rank of specific search results

-The portal enables you to adjust the search ranking of content from specific domains, subpages, and webpages. After sending a search query in the preview pane, each search result contains a list of adjustments you can make for it:

-| Adjustment | Description |

-||-|

-| Block | Moves the domain, subpage, or webpage to the Blocked list. Bing will exclude content from the selected site from appearing in the search results. |

-| Boost | Boosts content from the domain or subpage to be higher in the search results. |

-| Demote | Demotes content from the domain or subpage lower in the search results. You select whether to demote content from the domain or subpage that the webpage belongs to. |

-| Pin to top | Moves the domain, subpage, or webpage to the **Pinned** list. This Forces the webpage to appear as the top search result for a given search query. |

-Adjusting rank is not available for image or video searches.

-### Boosting and demoting search results

-You can super boost, boost, or demote any domain or subpage in the **Active** list. By default, all slices are added with no ranking adjustments. Slices of the web that are Super boosted or Boosted are ranked higher in the search results (with super boost ranking higher than boost). Items that are demoted are ranked lower in the search results.

-You can super boost, boost, or demote items by using the **Ranking Adjust** controls in the **Active** list, or by using the Boost and Demote controls in the Preview pane. The service adds the slice to your Active list and adjusts the ranking accordingly.

-> [!NOTE]

-> Boosting and demoting domains and subpages is one of many methods Bing Custom Search uses to determine the order of search results. Because of other factors influencing the ranking of different web content, the effects of adjusting rank may vary. Use the Preview pane to test the effects of adjusting the rank of your search results.

-Super boost, boost, and demote are not available for the image and video searches.

-## Pin slices to the top of search results

-The portal also lets you pin URLs to the top of search results for specific search terms, using the **Pinned** tab. Enter a URL and query to specify the webpage that will appear as the top result. Note that you can pin a maximum of one webpage per search query, and only indexed webpages will be displayed in searches. Pinning results is not available for image or video searches.

-You can pin a webpage to the top in two ways:

-* In the **Pinned** tab, enter the URL of the webpage to pin to the top, and its corresponding query.

-* In the **Preview** pane, enter a search query and click search. Find the webpage you want to pin for your query, and click **Pin to top**. the webpage and query will be added to the **Pinned** list.

-### Specify the pin's match condition

-By default, webpages are only pinned to the top of search results when a user's query string exactly matches one listed in the **Pinned** list. You can change this behavior by specifying one of the following match conditions:

-> [!NOTE]

-> All comparisons between the user's search query, and the pin's search query are case insensitive.

-| Value | Description |

-||-|

-| Starts with | The pin is a match if the user's query string starts with the pin's query string |

-| Ends with | The pin is a match if the user's query string ends with the pin's query string. |

-| Contains | The pin is a match if the user's query string contains the pin's query string. |

-To change the pin's match condition, click the pin's edit icon. In the **Query match condition** column, click the dropdown list and select the new condition to use. Then, click the save icon to save the change.

-### Change the order of your pinned sites

-To change the order of your pins, you can drag-and-drop the them, or edit their order number by clicking the "edit" icon in the **Controls** Column of the **Pinned** list.

-If multiple pins satisfy a match condition, Bing Custom Search will use the one highest in the list.

-## View statistics

-If you subscribed to Custom Search at the appropriate level (see the [pricing pages](https://azure.microsoft.com/pricing/details/cognitive-services/bing-custom-search/)), a **Statistics** tab is added to your production instances. The statistics tab shows details about how your Custom Search endpoints are used, including call volume, top queries, geographic distribution, response codes, and safe search. You can filter details using the provided controls.

-## Usage guidelines

-## Next steps

-description: Create tailored search experiences for topics that you care about. Users see search results tailored to the content they care about.

-# Custom Search

-Bing Custom Search enables you to create tailored search experiences for topics that you care about. Your users see search results tailored to the content they care about instead of having to page through search results that have irrelevant content.

-## Custom Search Endpoint

-To get results using the Bing Custom Search API, send a `GET` request to the following endpoint. Use the headers and URL parameters to define further specifications.

-Endpoint: Returns search suggestions as JSON results that are relevant to the user's input defined by `?q=""`.

-```

- GET https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/search

-```

-For examples that describe how to set up Custom Search sources, see the [tutorial](./tutorials/custom-search-web-page.md). For details about headers, parameters, market codes, response objects, errors, etc., see the [Bing Custom Search API v7](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference) reference.

-## Custom Search Response JSON

-A custom search request returns results as JSON objects, see [Response objects](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#response-objects).

-## Custom Autosuggest

-The Custom Autosuggest API lets you send a partial search query term to Bing and get back a list of suggested queries that you can configure. With Custom Autosuggest, you add suggestions returned by the API and optionally specify whether to include suggestions generated by Bing.

-## Custom Autosuggest Endpoint

-To request custom query suggestions, send a GET request to:

-```

-https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/Suggestions

-```

-For information about defining custom suggestions, see [Define custom search suggestions](define-custom-suggestions.md).

-## Custom Image Search

-The Custom Image Search API lets you send a search query to Bing and get back a list of relevant images from your Custom Search instance.

-## Custom Image Search Endpoint

-To request images from your Custom Search instance, send a GET request to the following URL:

-```

-https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/images/search

-```

-For information about configuring a Custom Search instance, see [Configure your custom search experience](./define-your-custom-view.md).

-## Next steps

-The **Bing** APIs support search actions that return results according to their type. All search endpoints return results as JSON response objects.  All endpoints support queries that return a specific language and/or location by longitude, latitude, and search radius.

-For complete information about the parameters supported by each endpoint, see the reference pages for each type.

-For examples of basic requests using the Custom Search API, see [Custom Search Quick-starts](/azure/cognitive-services/bing-custom-search/quick-start)

-description: High-level overview about using Bing Custom Search to get images from your custom view of the Web.

-# Get images from your custom view

-Bing Custom Images Search lets you enrich your custom search experience with images. Similar to web results, custom search supports searching for images in your instance's list of websites. You can get the images using the Bing Custom Images Search API or through the Hosted UI feature. Using the Hosted UI feature is simple to use and recommended for getting your search experience up and running in short order. For information about configuring your Hosted UI to include images, see [Configure your hosted UI experience](hosted-ui.md).

-If you want more control over displaying the search results, you can use the Bing Custom Images Search API. Because calling the API is similar to calling the Bing Image Search API, checkout [Bing Image Search](../bing-image-search/overview.md) for examples calling the API. But before you do that, familiarize yourself with the [Custom Images Search API reference](/rest/api/cognitiveservices-bingsearch/bing-custom-images-api-v7-reference) content. The main differences are the supported query parameters (you must include the customConfig query parameter) and the endpoint you send requests to.

-<!--

-## Next steps

-[Call your custom view](search-your-custom-view.md)

-description: High-level overview about using Bing Custom Search to get videos from your custom view of the Web.

-# Get videos from your custom view

-Bing Custom Videos Search lets you enrich your custom search experience with videos. Similar to web results, custom search supports searching for videos in your instance's list of websites. You can get the videos using the Bing Custom Videos Search API or through the Hosted UI feature. Using the Hosted UI feature is simple to use and recommended for getting your search experience up and running in short order. For information about configuring your Hosted UI to include videos, see [Configure your hosted UI experience](hosted-ui.md).

-If you want more control over displaying the search results, you can use the Bing Custom Videos Search API. Because calling the API is similar to calling the Bing Video Search API, checkout [Bing Video Search](../bing-video-search/overview.md) for examples calling the API. But before you do that, familiarize yourself with the [Custom Videos Search API reference](/rest/api/cognitiveservices-bingsearch/bing-custom-videos-api-v7-reference) content. The main differences are the supported query parameters (you must include the customConfig query parameter) and the endpoint you send requests to.

-<!--

-## Next steps

-[Call your custom view](search-your-custom-view.md)

-description: Use this article to configure and integrate a hosted UI for Bing Custom Search.

-# Configure your hosted UI experience

-Bing Custom Search provides a hosted UI that you can easily integrate into your webpages and web applications as a JavaScript code snippet. Using the Bing Custom Search portal, you can configure the layout, color, and search options of the UI.

-## Configure the custom hosted UI

-To configure a hosted UI for your web applications, follow these steps. As you make changes, the pane on the right will give you a preview of your UI. The displayed search results are not actual results for your instance.

-1. Sign in to Bing Custom Search [portal](https://customsearch.ai).

-

-2. Select your Bing Custom Search instance.

-3. Click the **Hosted UI** tab.

-

-4. Select a layout.

- - Search bar and results (default): Displays a search box with search results below it.

- - Results only: Displays search results only, without a search box. When using this layout, you must provide the search query (`&q=<query string>`). Add the query parameter to the request URL in the JavaScript snippet, or the HTML endpoint link.

- - Pop-over: Provides a search box and displays the search results in a sliding overlay.

-5. Select a color theme. You can customize the colors to fit your application by clicking **Customize theme**. To change a color, either enter the color's RGB HEX value (for example, `#366eb8`), or click on the color preview.

- You can preview your changes on the right side of the portal. Clicking **Reset to default** will revert your changes to the default colors for the selected theme.

- > [!NOTE]

- > Consider accessibility when choosing colors.

-6. Under **Additional Configurations**, provide values as appropriate for your app. These settings are optional. To see the effect of applying or removing them, see the preview pane on the right. Available configuration options are:

-7. Enter the search subscription key or choose one from the dropdown list. The dropdown list is populated with keys from your Azure account's subscriptions. See [Azure AI services API account](../cognitive-services-apis-create-account.md).

-8. If you enabled autosuggest, enter the autosuggest subscription key or choose one from the dropdown list. The dropdown list is populated with keys from your Azure account's subscriptions. Custom Autosuggest requires a specific subscription tier, see the [pricing](https://azure.microsoft.com/pricing/details/cognitive-services/bing-custom-search/).

-## Consume custom UI

-To consume the hosted UI, either:

-

- ```html

- <html>

- <body>

- <script type="text/javascript"

- id="bcs_js_snippet"

- src="https://ui.customsearch.ai /api/ux/rendering-js?customConfig=<YOUR-CUSTOM-CONFIG-ID>&market=en-US&safeSearch=Moderate&version=latest&q=">

- </script>

- </body>

- </html>

- ```

-

- `https://ui.customsearch.ai/hosted?customConfig=YOUR-CUSTOM-CONFIG-ID`

-

- > [!NOTE]

- > Add the following query parameters to the URL as needed. For information about these parameters, see [Custom Search API](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#query-parameters) reference.

- >

- > - q

- > - mkt

- > - safesearch

- > - setlang

- > [!IMPORTANT]

- > The page cannot display your privacy statement or other notices and terms. Suitability for your use may vary.

-For additional information, including your Custom Configuration ID, go to **Endpoints** under the **Production** tab.

-## Configuration options

-You can configure the behavior of your hosted UI by clicking **Additional Configurations**, and providing values. These settings are optional. To see the effect of applying or removing them, see the preview pane on the right.

-### Web search configurations

-The following configurations are shown if you click **Show advanced configurations**:

-### Image search configurations

-The following configuration is shown if you click **Show advanced configurations**.

-

-### Video search configurations

-The following configuration is shown if you click **Show advanced configurations**.

-

-### Miscellaneous configurations

-The following configurations are shown if you click **Show advanced configurations**.

-|Column1 |Column2 |

-|||

-|Search box text placeholder | Text displayed in the search box prior to input. |

-|Title link url |Target for the title link. |

-|Logo URL | Image displayed next to the title. |

-|Favicon | Icon displayed in the browser's title bar. |

-The following configurations apply only if you consume the Hosted UI through the HTML endpoint (they don't apply if you use the JavaScript snippet).

-## Next steps

-description: A list of supported languages and regions for the Bing Custom Search API.

-# Language and region support for the Bing Custom Search API

-The Bing Custom Search API supports more than three dozen countries/regions, many with more than one language.

-Although it's optional, the request should specify the [mkt](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#mkt) query parameter, which identifies the market where you want the results to come from. For a list of optional query parameters, see [Query Parameters](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#query-parameters)

-You can specify a country/region using the `cc` query parameter. If you specify a country/region, you must also specify one or more language codes using the `Accept-Language` header. The supported languages vary by country/region; they are given for each country/region in the **Markets** table.

-The `Accept-Language` header and the `setLang` query parameter are mutually exclusiveΓÇödo not specify both. For details, see [Accept-Language](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#acceptlanguage).

-## Countries/Regions

-|Country/region|Code|

-|-|-|

-|Argentina|AR|

-|Australia|AU|

-|Austria|AT|

-|Belgium|BE|

-|Brazil|BR|

-|Canada|CA|

-|Chile|CL|

-|Denmark|DK|

-|Finland|FI|

-|France|FR|

-|Germany|DE|

-|Hong Kong SAR|HK|

-|India|IN|

-|Indonesia|ID|

-|Italy|IT|

-|Japan|JP|

-|Korea|KR|

-|Malaysia|MY|

-|Mexico|MX|

-|Netherlands|NL|

-|New Zealand|NZ|

-|Norway|NO|

-|China|CN|

-|Poland|PL|

-|Portugal|PT|

-|Philippines|PH|

-|Russia|RU|

-|Saudi Arabia|SA|

-|South Africa|ZA|

-|Spain|ES|

-|Sweden|SE|

-|Switzerland|CH|

-|Taiwan|TW|

-|T├╝rkiye|TR|

-|United Kingdom|GB|

-|United States|US|

-## Markets

-|Country/region|Language|Market Code|

-|-|--|--|

-|Argentina|Spanish|es-AR|

-|Australia|English|en-AU|

-|Austria|German|de-AT|

-|Belgium|Dutch|nl-BE|

-|Belgium|French|fr-BE|

-|Brazil|Portuguese|pt-BR|

-|Canada|English|en-CA|

-|Canada|French|fr-CA|

-|Chile|Spanish|es-CL|

-|Denmark|Danish|da-DK|

-|Finland|Finnish|fi-FI|

-|France|French|fr-FR|

-|Germany|German|de-DE|

-|Hong Kong SAR|Traditional Chinese|zh-HK|

-|India|English|en-IN|

-|Indonesia|English|en-ID|

-|Italy|Italian|it-IT|

-|Japan|Japanese|ja-JP|

-|Korea|Korean|ko-KR|

-|Malaysia|English|en-MY|

-|Mexico|Spanish|es-MX|

-|Netherlands|Dutch|nl-NL|

-|New Zealand|English|en-NZ|

-|Norway|Norwegian|no-NO|

-|China|Chinese|zh-CN|

-|Poland|Polish|pl-PL|

-|Portugal|Portuguese|pt-PT|

-|Philippines|English|en-PH|

-|Russia|Russian|ru-RU|

-|Saudi Arabia|Arabic|ar-SA|

-|South Africa|English|en-ZA|

-|Spain|Spanish|es-ES|

-|Sweden|Swedish|sv-SE|

-|Switzerland|French|fr-CH|

-|Switzerland|German|de-CH|

-|Taiwan|Traditional Chinese|zh-TW|

-|T├╝rkiye|Turkish|tr-TR|

-|United Kingdom|English|en-GB|

-|United States|English|en-US|

-|United States|Spanish|es-US|

-description: The Bing Custom Search API enables you to create tailored search experiences for topics that you care about.

-# What is the Bing Custom Search API?

-The Bing Custom Search API enables you to create tailored ad-free search experiences for topics that you care about. You can specify the domains and webpages for Bing to search, as well as pin, boost, or demote specific content to create a custom view of the web and help your users quickly find relevant search results.

-## Features

-|Feature |Description |

-|||

-|[Custom real-time search suggestions](define-custom-suggestions.md) | Provide search suggestions that can be displayed as a dropdown list as your users type. |

-|[Custom image search experiences](get-images-from-instance.md) | Enable your users to search for images from the domains and websites specified in your custom search instance. |

-|[Custom video search experiences](get-videos-from-instance.md) | Enable your users to search for videos from the domains and sites specified in your custom search instance. |

-|[Share your custom search instance](share-your-custom-search.md) | Collaboratively edit and test your search instance by sharing it with members of your team. |

-|[Configure a UI for your applications and websites](hosted-ui.md) | Provides a hosted UI that you can easily integrate into your webpages and web applications as a JavaScript code snippet. |

-## Workflow

-You can create a customized search instance by using the [Bing Custom Search portal](https://customsearch.ai). The portal enables you to create a custom search instance that specifies the domains, websites, and webpages that you want Bing to search, along with the ones that you donΓÇÖt want it to search. You can also use the portal to: preview the search experience, adjust the search rankings that the API provides, and optionally configure a searchable user interface to be rendered in your websites and applications.

-After creating your search instance, you can integrate it (and optionally, a user interface) into your website or application by calling the Bing Custom Search API:

-

-## Next steps

-To get started quickly, see [Create your first Bing Custom Search instance](quick-start.md).

-For details about customizing your search instance, see [Define a custom search instance](define-your-custom-view.md).

-Be sure to read [Bing Use and Display Requirements](../bing-web-search/use-display-requirements.md) for using search results in your services and applications.

-Visit the [Bing Search API hub page](../bing-web-search/overview.md) to explore the other available APIs.

-Familiarize yourself with the reference content for each of the custom search endpoints. The reference contains the endpoints, headers, and query parameters that you'd use to request search results. It also includes definitions of the response objects.

-description: Use this quickstart to create a custom Bing instance that can search domains and webpages that you define.

-# Quickstart: Create your first Bing Custom Search instance

-To use Bing Custom Search, you need to create a custom search instance that defines your view or slice of the web. This instance contains the public domains, websites, and webpages that you want to search, along with any ranking adjustments you may want.

-To create the instance, use the [Bing Custom Search portal](https://customsearch.ai).

-

-## Prerequisites

-## Create a custom search instance

-To create a Bing Custom Search instance:

-1. Click **Get Started** on the [Bing Custom Search portal](https://customsearch.ai) webpage, and sign in with your Microsoft account.

-2. Click **New Instance**, and enter a descriptive name. You can change the name of your instance at any time.

-

-3. On the **Active** tab under **Search Experience**, enter the URL of one or more websites you want to include in your search.

- > [!NOTE]

- > Bing Custom Search instances will only return results for domains, and webpages that are public and have been indexed by Bing.

-4. You can use the right side of the Bing Custom Search portal to enter a query and examine the search results returned by your search instance. If no results are returned, try entering a different URL.

-5. Click **Publish** to publish your changes to the production environment, and update the instance's endpoints.

-6. Click on the **Production** tab under **Endpoints**, and copy your **Custom Configuration ID**. You need this ID to call the Custom Search API by appending it to the `customconfig=` query parameter in your calls.

-## Next steps

-> [!div class="nextstepaction"]

-> [Quickstart: Call your Bing Custom Search endpoint](./call-endpoint-csharp.md)

-description: The Custom Search API offers client libraries that makes it easy to integrate search capabilities into your applications. Use this quickstart to start sending search requests, and get back results.

-zone_pivot_groups: programming-languages-set-eleven

-# Quickstart: Use the Bing Custom Search client library

-description: After you've configured your custom search experience, you can test it from within the Bing Custom Search portal.

-# Call your Bing Custom Search instance from the Portal

-After you've configured your custom search experience, you can test it from within the Bing Custom Search [portal](https://customsearch.ai).

-

-## Create a search query

-After you've signed into the Bing Custom Search [portal](https://customsearch.ai), select your search instance and click the **Production** tab. Under **Endpoints**, select an API endpoint (for example, Web API). Your subscription determines what endpoints are shown.

-To create a search query, enter the parameter values for your endpoint. Note that the parameters displayed in the portal may change depending on the endpoint you choose. See the [Custom Search API reference](/rest/api/cognitiveservices-bingsearch/bing-custom-search-api-v7-reference#query-parameters) for more information. To change the subscription your search instance uses, add the appropriate subscription key, and update the appropriate market and/or language parameters.

-Some important parameters are below:

-|Parameter |Description |

-|||

-|Query | The search term to search for. Only available for Web, Image, Video, and Autosuggest endpoints |

-|Custom Configuration ID | The configuration ID of the selected Custom Search instance. This field is read only. |

-|Market | The market that results will originate from. Only available for the Web, Image, Video, and Hosted UI endpoints. |

-|Subscription Key | The subscription key to test with. You can select a key from the dropdown list or enter one manually. |

-Clicking **Additional Parameters** reveals the following parameters:

-|Parameter |Description |

-|||

-|Safe Search | A filter used to filter webpages for adult content. Only available for the Web, Image, Video, and Hosted UI endpoints. Note that Bing Custom Video Search only supports two values: `moderate` and `strict`. |

-|User Interface Language | The language used for user interface strings. For example, if you enable images and videos in Hosted UI, the **Image** and **Video** tabs use the specified language. |

-|Count | The number of search results to return in the response. Available only for Web, Image, and Video endpoints. |

-|Offset | The number of search results to skip before returning results. Available only for Web, Image, and Video endpoints. |

-

-After you've specified all required options, click **Call** to view the JSON response in the right pane. If you select the Hosted UI endpoint, you can test the search experience in the bottom pane.

-## Change your Bing Custom Search subscription

-You can change the subscription associated with your Bing Custom Search instance without creating a new instance. To have API calls sent and charged to a new subscription, create a new Bing Custom Search resource in the Azure portal. Use the new subscription key in your API requests, along with your instance's custom configuration ID.

-## Next steps

-description: Easily allow collaborative editing and testing of your instance by sharing it with members of your team.

-# Share your Custom Search instance

-You can easily allow collaborative editing and testing of your instance by sharing it with members of your team. You can share your instance with anyone using just their email address. To share an instance:

-After adding the email address, it's added to the **Instance shared with** list. Repeat the process for each person you want to share your instance with.

-To add someone's email to the list, it isn't necessary for them to have a Custom Search account. They will need to sign up for Custom Search before they make configuration changes though. After you share an instance with someone, they'll see it in their list of Custom Search instances. Only one person can modify an instance at a time. If you try to modify an instance that someone else is editing, a warning is shown. An instance can be shared with a maximum of 10 users.

-## Stop sharing

-To stop sharing an instance with someone, use the remove icon to remove their email address from the list. This also removes the instance from their list of instances.

-## Next steps

-description: Learn how to configure a custom Bing search instance and integrate it into a web page with this tutorial.

-# Tutorial: Build a Custom Search web page

-Bing Custom Search enables you to create tailored search experiences for topics that you care about. For example, if you own a martial arts website that provides a search experience, you can specify the domains, sub-sites, and webpages that Bing searches. Your users see search results tailored to the content they care about instead of paging through general search results that may contain irrelevant content.

-This tutorial demonstrates how to configure a custom search instance and integrate it into a new web page.

-The tasks covered are:

-> [!div class="checklist"]

-> - Create a custom search instance

-> - Add active entries

-> - Add blocked entries

-> - Add pinned entries

-> - Integrate custom search into a web page

-## Prerequisites

-## Create a custom search instance

-To create a Bing Custom Search instance:

-1. Open an internet browser.

-

-2. Navigate to the custom search [portal](https://customsearch.ai).

-

-3. Sign in to the portal using a Microsoft account (MSA). If you don't have an MSA, click **Create a Microsoft account**. If it's your first time using the portal, it will ask for permissions to access your data. Click **Yes**.

-

-4. After signing in, click **New custom search**. In the **Create a new custom search instance** window, enter a name that's meaningful and describes the type of content the search returns. You can change the name at any time.

-

- 

-

-5. Click OK, specify a URL and whether to include subpages of the URL.

-

- 

-## Add active entries

-To include results from specific websites or URLs, add them to the **Active** tab.

-1. On the **Configuration** page, click the **Active** tab and enter the URL of one or more websites you want to include in your search.

- 

-2. To confirm that your instance returns results, enter a query in the preview pane on the right. Bing returns only results for public websites that it has indexed.

-## Add blocked entries

-To exclude results from specific websites or URLs, add them to the **Blocked** tab.

-1. On the **Configuration** page, click the **Blocked** tab and enter the URL of one or more websites you want to exclude from your search.

- 

-2. To confirm that your instance doesn't return results from the blocked websites, enter a query in the preview pane on the right.

-## Add pinned entries

-To pin a specific webpage to the top of the search results, add the webpage and query term to the **Pinned** tab. The **Pinned** tab contains a list of webpage and query term pairs that specify the webpage that appears as the top result for a specific query. The webpage is pinned only if the user's query string matches the pin's query string based on pin's match condition. Only indexed webpages will be displayed in searches. For more information, see [Define your custom view](../define-your-custom-view.md#pin-slices-to-the-top-of-search-results).

-1. On the **Configuration** page, click the **Pinned** tab and enter the webpage and query term of the webpage that you want returned as the top result.

-

-2. By default, the user's query string must exactly match your pin's query string for Bing to return the webpage as the top result. To change the match condition, edit the pin (click the pencil icon), click Exact in the **Query match condition** column, and select the match condition that's right for your application.

-

- 

-

-3. To confirm that your instance returns the specified webpage as the top result, enter the query term you pinned in the preview pane on the right.

-## Configure Hosted UI

-Custom Search provides a hosted UI to render the JSON response of your custom search instance. To define your UI experience:

-1. Click the **Hosted UI** tab.

-

-2. Select a layout.

-

- 

-

-3. Select a color theme.

-

- 

- If you need to fine-tune the color theme to better integrate with your web app, click **Customize theme**. Not all color configurations apply to all layout themes. To change a color, enter the color's RGB HEX value (for example, #366eb8) in the corresponding text box. Or, click the color button and then click the shade that works for you. Always think about accessibility when selecting colors.

-

- 

-

-4. Specify additional configuration options.

-

- 

-

- To get advanced configurations, click **Show advanced configurations**. This adds configurations such as *Link target* to Web search options, *Enable filters* to Image and Video options, and *Search box text placeholder* to Miscellaneous options.

- 

-

-5. Select your subscription keys from the dropdown lists. Or, you can enter the subscription key manually.

-

- 

-<a name="consuminghostedui"></a>

-## Consuming Hosted UI

-There are two ways to consume the hosted UI.

-The remainder of this tutorial illustrates **Option 1: JavaScript snippet**.

-## Set up your Visual Studio solution

-1. Open **Visual Studio** on your computer.

-

-2. On the **File** menu, select **New**, and then choose **Project**.

-

-3. In the **New Project** window, select **Visual C# / Web / ASP.NET Core Web Application**, name your project, and then click **OK**.

-

- 

-

-4. In the **New ASP.NET Core Web Application** window, select **Web Application** and click **OK**.

-

- 

-## Edit index.cshtml

-1. In the **Solution Explorer**, expand **Pages** and double-click **index.cshtml** to open the file.

-

- 

-

-2. In index.cshtml, delete everything starting from line 7 and below.

-

- ```razor

- @page

- @model IndexModel

- @{

- ViewData["Title"] = "Home page";

- }

- ```

-

-3. Add a line break element and a div to act as a container.

-

- ```html

- @page

- @model IndexModel

- @{

- ViewData["Title"] = "Home page";

- }

- <br />

- <div id="customSearch"></div>

- ```

-

-4. In the **Hosted UI** page, scroll down to the section titled **Consuming the UI**. Click the *Endpoints* to access the JavaScript snippet. You can also get to the snippet by clicking **Production** and then the **Hosted UI** tab.

-

- <!-- Get new screenshot after prod gets new bits

- 

- -->

-

-5. Paste the script element into the container you added.

-

- ``` html

- @page

- @model IndexModel

- @{

- ViewData["Title"] = "Home page";

- }

- <br />

- <div id="customSearch">

- <script type="text/javascript"

- id="bcs_js_snippet"

- src="https://ui.customsearch.ai /api/ux/rendering-js?customConfig=<YOUR-CUSTOM-CONFIG-ID>&market=en-US&safeSearch=Moderate&version=latest&q=">

- </script>

- </div>

- ```

-

-6. In the **Solution Explorer**, right click on **wwwroot** and click **View in Browser**.

-

- 

-Your new custom search web page should look similar to this:

-

-Performing a search renders results like this:

-

-## Next steps

-> [!div class="nextstepaction"]

-> [Call Bing Custom Search endpoint (C#)](../call-endpoint-csharp.md)

-description: Use the Bing Entity Search API to extract and search for entities and places from search queries.

-# Searching for entities with the Bing Entity API

-## Suggest search terms with the Bing Autosuggest API

-If you provide a search box where the user enters their search term, use the [Bing Autosuggest API](../../bing-autosuggest/get-suggested-search-terms.md) to improve the experience. The API returns suggested query strings based on partial search terms as the user types.

-After the user enters their search term, URL encode the term before setting the [q](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#query) query parameter. For example, if the user enters *Marcus Appel*, set `q` to *Marcus+Appel* or *Marcus%20Appel*.

-If the search term contains a spelling mistake, the search response includes a [QueryContext](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#querycontext) object. The object shows the original spelling and the corrected spelling that Bing used for the search.

-```json

-"queryContext": {

- "originalQuery": "hollo wrld",

- "alteredQuery": "hello world",

- "alterationOverrideQuery": "+hollo wrld",

- "adultIntent": false

-}

-```

-## The Bing Entity Search API response

-The API response contains a [SearchResponse](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#searchresponse) object. If Bing finds an entity or place that's relevant, the object includes the `entities` field, `places` field, or both. Otherwise, the response object does not include either field.

-> [!NOTE]

-> Entity responses support multiple markets, but the Places response supports only US Business locations.

-The `entities` field is an [EntityAnswer](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference) object that contains a list of [Entity](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#entity) objects (see the `value` field). The list may contain a single dominant entity, multiple disambiguation entities, or both.

-A dominant entity is returned when Bing believes it to be the only entity that satisfies the request (there is no ambiguity as to which entity satisfies the request). If multiple entities could satisfy the request, the list contains more than one disambiguation entity. For example, if the request uses the generic title of a movie franchise, the list likely contains disambiguation entities. But, if the request specifies a specific title from the franchise, the list likely contains a single dominant entity.

-Entities include well-known personalities such as singers, actors, athletes, models, etc.; places and landmarks such as Mount Rainier or Lincoln Memorial; and things such as a banana, goldendoodle, book, or movie title. The [entityPresentationInfo](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#entitypresentationinfo) field contains hints that identify the entity's type. For example, if it's a person, movie, animal, or attraction. For a list of possible types, see [Entity Types](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#entity-types)

-```json

-"entityPresentationInfo": {

- "entityScenario": "DominantEntity",

- "entityTypeHints": ["Attraction"],

- "entityTypeDisplayHint": "Mountain"

-}, ...

-```

-The following shows a response that includes a dominant and disambiguation entity.

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "Mount Rainier"

- },

- "entities": {

- "value": [{

- "contractualRules": [{

- "_type": "ContractualRules/LicenseAttribution",

- "targetPropertyName": "description",

- "mustBeCloseToContent": true,

- "license": {

- "name": "CC-BY-SA",

- "url": "https://creativecommons.org/licenses/by-sa/3.0/"

- },

- "licenseNotice": "Text under CC-BY-SA license"

- },

- {

- "_type": "ContractualRules/LinkAttribution",

- "targetPropertyName": "description",

- "mustBeCloseToContent": true,

- "text": "contoso.com",

- "url": "http://contoso.com/mount_rainier"

- },

- {

- "_type": "ContractualRules/MediaAttribution",

- "targetPropertyName": "image",

- "mustBeCloseToContent": true,

- "url": "http://contoso.com/mount-rainier"

- }],

- "webSearchUrl": "https://www.bing.com/search?q=Mount%20Rainier...",

- "name": "Mount Rainier",

- "url": "http://www.northwindtraders.com/",

- "image": {

- "name": "Mount Rainier",

- "thumbnailUrl": "https://www.bing.com/th?id=A4ae343983daa4...",

- "provider": [{

- "_type": "Organization",

- "url": "http://contoso.com/mount_rainier"

- }],

- "hostPageUrl": "http://contoso.com/commons/7/72/mount_rain...",

- "width": 110,

- "height": 110

- },

- "description": "Mount Rainier is 14,411 ft tall and the highest mountain...",

- "entityPresentationInfo": {

- "entityScenario": "DominantEntity",

- "entityTypeHints": ["Attraction"]

- },

- "bingId": "38b9431e-cf91-93be-0584-c42a3ecbfdc7"

- },

- {

- "contractualRules": [{

- "_type": "ContractualRules/MediaAttribution",

- "targetPropertyName": "image",

- "mustBeCloseToContent": true,

- "url": "http://contoso.com/mount_rainier_national_park"

- }],

- "webSearchUrl": "https://www.bing.com/search?q=Mount%20Rainier%20National...",

- "name": "Mount Rainier National Park",

- "url": "http://worldwideimporters.com/",

- "image": {

- "name": "Mount Rainier National Park",

- "thumbnailUrl": "https://www.bing.com/th?id=A91bdc5a1b648a695a39...",

- "provider": [{

- "_type": "Organization",

- "url": "http://contoso.com/mount_rainier_national_park"

- }],

- "hostPageUrl": "http://contoso.com/en/7/7a...",

- "width": 50,

- "height": 50

- },

- "description": "Mount Rainier National Park is a United States National Park...",

- "entityPresentationInfo": {

- "entityScenario": "DisambiguationItem",

- "entityTypeHints": ["Organization"]

- },

- "bingId": "29d4b681-227a-3924-7bb1-8a54e8666b8c"

- }]

- }

-}

-```

-The entity includes a `name`, `description`, and `image` field. When you display these fields in your user experience, you must attribute them. The `contractualRules` field contains a list of attributions that you must apply. The contractual rule identifies the field that the attribution applies to. For information about applying attribution, see [Attribution](#data-attribution).

-```json

-"contractualRules": [{

- "_type": "ContractualRules/LicenseAttribution",

- "targetPropertyName": "description",

- "mustBeCloseToContent": true,

- "license": {

- "name": "CC-BY-SA",

- "url": "https://creativecommons.org/licenses/by-sa/3.0/"

- },

- "licenseNotice": "Text under CC-BY-SA license"

-},

-{

- "_type": "ContractualRules/LinkAttribution",

- "targetPropertyName": "description",

- "mustBeCloseToContent": true,

- "text": "contoso.com",

- "url": "http://contoso.com/wiki/Mount_Rainier"

-},

-{

- "_type": "ContractualRules/MediaAttribution",

- "targetPropertyName": "image",

- "mustBeCloseToContent": true,

- "url": "http://contoso.com/wiki/Mount_Rainier"

-}], ...

-```

-When you display the entity information (name, description, and image), you must also use the URL in the `webSearchUrl` field to link to the Bing search results page that contains the entity.

-## Find places

-The `places` field is a [LocalEntityAnswer](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference) object that contains a list of [Place](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#place) objects (see the [Entity Types](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#entity-types) for more information). The list contains one or more local entities that satisfy the request.

-Places include restaurant, hotels, or local businesses. The [entityPresentationInfo](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#entitypresentationinfo) field contains hints that identify the local entity's type. The list contains a list of hints such as Place, LocalBusiness, Restaurant. Each successive hint in the array narrows the entity's type. For a list of possible types, see [Entity Types](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#entity-types)

-```json

-"entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": ["Place",

- "LocalBusiness",

- "Restaurant"]

-}, ...

-```

-> [!NOTE]

-> Entity responses support multiple markets, but the Places response supports only US Business locations.

-Local aware entity queries such as *restaurant near me* require the user's location to provide accurate results. Your requests should always use the X-Search-Location and X-MSEdge-ClientIP headers to specify the user's location. If Bing thinks the query would benefit from the user's location, it sets the `askUserForLocation` field of [QueryContext](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#querycontext) to **true**.

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "Sinful Bakery and Cafe",

- "askUserForLocation": true

- },

- ...

-}

-```

-A place result includes the place's name, address, telephone number, and URL to the entity's website. When you display the entity information, you must also use the URL in the `webSearchUrl` field to link to the Bing search results page that contains the entity.

-```json

-"places": {

- "value": [{

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Sinful%20Bakery...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "http://libertysdelightfulsinfulbakeryandcafe.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": ["Place",

- "LocalBusiness",

- "Restaurant"]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- }]

-}

-```

-> [!NOTE]

-> You, or a third party on your behalf, may not use, retain, store, cache, share, or distribute any data from the Entities API for the purpose of testing, developing, training, distributing or making available any non-Microsoft service or feature.

-## Data attribution

-Bing Entity API responses contain information owned by third parties. You are responsible to ensure your use is appropriate, for example by complying with any creative commons license your user experience may rely on.

-If an answer or result includes the `contractualRules`, `attributions`, or `provider` fields, you must attribute the data. If the answer does not include any of these fields, no attribution is required. If the answer includes the `contractualRules` field and the `attributions` and/or `provider` fields, you must use the contractual rules to attribute the data.

-The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a `provider` field. The MediaAttribution rule identifies the image as the target of the rule, so you'd ignore the image's `provider` field and instead use the MediaAttribution rule to provide attribution.

-```json

-"value": [{

- "contractualRules": [

- ...

- {

- "_type": "ContractualRules/MediaAttribution",

- "targetPropertyName": "image",

- "mustBeCloseToContent": true,

- "url": "http://contoso.com/mount_rainier"

- }

- ],

- ...

- "image": {

- "name": "Mount Rainier",

- "thumbnailUrl": "https://www.bing.com/th?id=A46378861201...",

- "provider": [{

- "_type": "Organization",

- "url": "http://contoso.com/mount_rainier"

- }],

- "hostPageUrl": "http://www.graphicdesigninstitute.com/Uploaded...",

- "width": 110,

- "height": 110

- },

- ...

-}]

-```

-If a contractual rule includes the `targetPropertyName` field, the rule applies only to the targeted field. Otherwise, the rule applies to the parent object that contains the `contractualRules` field.

-In the following example, the `LinkAttribution` rule includes the `targetPropertyName` field, so the rule applies to the `description` field. For rules that apply to specific fields, you must include a line immediately following the targeted data that contains a hyperlink to the provider's website. For example, to attribute the description, include a line immediately following the description text that contains a hyperlink to the data on the provider's website, in this case create a link to contoso.com.

-```json

-"entities": {

- "value": [{

- ...

- "description": "Marcus Appel is a former American....",

- ...

- "contractualRules": [{

- "_type": "ContractualRules/LinkAttribution",

- "targetPropertyName": "description",

- "mustBeCloseToContent": true,

- "text": "contoso.com",

- "url": "http://contoso.com/cr?IG=B8AD73..."

- },

- ...

-

-```

-### License attribution

-If the list of contractual rules includes a [LicenseAttribution](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#licenseattribution) rule, you must display the notice on the line immediately following the content that the license applies to. The `LicenseAttribution` rule uses the `targetPropertyName` field to identify the property that the license applies to.

-The following shows an example that includes a `LicenseAttribution` rule.

-

-The license notice that you display must include a hyperlink to the website that contains information about the license. Typically, you make the name of the license a hyperlink. For example, if the notice is **Text under CC-BY-SA license** and CC-BY-SA is the name of the license, you would make CC-BY-SA a hyperlink.

-### Link and text attribution

-The [LinkAttribution](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#linkattribution) and [TextAttribution](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#textattribution) rules are typically used to identify the provider of the data. The `targetPropertyName` field identifies the field that the rule applies to.

-To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). The line should be clearly labeled to indicate that the providers are the source of the data. For example, "Data from: contoso.com". For `LinkAttribution` rules, you must create a hyperlink to the provider's website.

-The following shows an example that includes `LinkAttribution` and `TextAttribution` rules.

-

-### Media attribution

-If the entity includes an image and you display it, you must provide a click-through link to the provider's website. If the entity includes a [MediaAttribution](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#mediaattribution) rule, use the rule's URL to create the click-through link. Otherwise, use the URL included in the image's `provider` field to create the click-through link.

-The following shows an example that includes an image's `provider` field and contractual rules. Because the example includes the contractual rule, you ignore the image's `provider` field and apply the `MediaAttribution` rule.

-

-### Search or search-like experience

-Just like with Bing Web Search API, the Bing Entity Search API may only be used as a result of a direct user query or search, or as a result of an action within an app or experience that logically can be interpreted as a userΓÇÖs search request. For illustration purposes, the following are some examples of acceptable search or search-like experiences.

-If you are not sure if your experience can be considered a search-like experience, it is recommended that you check with Microsoft.

-## Throttling requests

-## Next steps

-* Try a [Quickstart](../quickstarts/csharp.md) to get started searching for entities with the Bing Entity Search API.

-description: The Bing Entity Search API sends a search query to Bing and gets results that include entities and places.

-# Sending search requests to the Bing Entity Search API

-The Bing Entity Search API sends a search query to Bing and gets results that include entities and places. Place results include restaurants, hotel, or other local businesses. For places, the query can specify the name of the local business or it can ask for a list (for example, restaurants near me). Entity results include persons, places, or things. Place in this context is tourist attractions, states, countries/regions, etc.

-## The endpoint

-To get entity and place search results, send a GET request to the following endpoint:

-```

-https://api.cognitive.microsoft.com/bing/v7.0/entities

-```

-Requests must use the HTTPS protocol.

-We recommend that all requests originate from a server. Distributing the key as part of a client application provides more opportunity for a malicious third party to access it. Also, making calls from a server provides a single upgrade point for future versions of the API.

-## Specifying query parameters and headers

-The request must specify the [q](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#query) query parameter, which contains the user's search term. The request must also specify the [mkt](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#mkt) query parameter, which identifies the market where you want the results to come from. For a list of optional query parameters, see [Query Parameters](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#query-parameters). URL encode all query parameters.

-

-The request must specify the [Ocp-Apim-Subscription-Key](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#subscriptionkey) header. Although optional, you are encouraged to also specify the following headers:

-

-The client IP and location headers are important for returning location aware content.

-For a list of all request and response headers, see [Headers](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#headers).

-## The request

-The following shows an entities request that includes all the suggested query parameters and headers.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/entities?q=mount+rainier&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-Search-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-If it's your first time calling any of the Bing APIs, don't include the client ID header. Only include the client ID if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

-## The response

-The following shows the response to the previous request. The example also shows the Bing-specific response headers. For information about the response object, see [SearchResponse](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#searchresponse).

-```json

-BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC

-X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869

-BingAPIs-Market: en-US

-{

- "_type" : "SearchResponse",

- "queryContext" : {

- "originalQuery" : "mount rainier"

- },

- "entities" : {

- "queryScenario" : "DominantEntity",

- "value" : [{

- "contractualRules" : [{

- "_type" : "ContractualRules\/LicenseAttribution",

- "targetPropertyName" : "description",

- "mustBeCloseToContent" : true,

- "license" : {

- "name" : "CC-BY-SA",

- "url" : "http:\/\/creativecommons.org\/licenses\/by-sa\/3.0\/"

- },

- "licenseNotice" : "Text under CC-BY-SA license"

- },

- {

- "_type" : "ContractualRules\/LinkAttribution",

- "targetPropertyName" : "description",

- "mustBeCloseToContent" : true,

- "text" : "en.wikipedia.org",

- "url" : "http:\/\/en.wikipedia.org\/wiki\/Mount_Rainier"

- },

- {

- "_type" : "ContractualRules\/MediaAttribution",

- "targetPropertyName" : "image",

- "mustBeCloseToContent" : true,

- "url" : "http:\/\/en.wikipedia.org\/wiki\/Mount_Rainier"

- }],

- "webSearchUrl" : "https:\/\/www.bing.com\/search?q=Mount%20Rainier...",

- "name" : "Mount Rainier",

- "image" : {

- "name" : "Mount Rainier",

- "thumbnailUrl" : "https:\/\/www.bing.com\/th?id=A21890c0e1f...",

- "provider" : [{

- "_type" : "Organization",

- "url" : "http:\/\/en.wikipedia.org\/wiki\/Mount_Rainier"

- }],

- "hostPageUrl" : "http:\/\/upload.wikimedia.org\/wikipedia...",

- "width" : 110,

- "height" : 110

- },

- "description" : "Mount Rainier, Mount Tacoma, or Mount Tahoma is the highest...",

- "entityPresentationInfo" : {

- "entityScenario" : "DominantEntity",

- "entityTypeHints" : ["Attraction"],

- "entityTypeDisplayHint" : "Mountain"

- },

- "bingId" : "9ae3e6ca-81ea-6fa1-ffa0-42e1d78906"

- }]

- }

-}

-```

-## Next steps

-* [Searching for entities with the Bing Entity API](search-for-entities.md)

-* [Bing API Use and Display Requirements](../../bing-web-search/use-display-requirements.md)

-description: The Bing Entity Search API has one endpoint that returns entities from the Web based on a query. These search results are returned in JSON.

-# Bing Entity Search API endpoint

-The Bing Entity Search API has one endpoint that returns entities from the Web based on a query. These search results are returned in JSON.

-## Get entity results from the endpoint

-To get entity results using the **Bing API**, send a `GET` request to the following endpoint. Use [headers](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#headers) and [query parameters](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference#query-parameters) to customize your search request. Search requests can be sent using the `?q=` parameter.

-```cURL

- GET https://api.cognitive.microsoft.com/bing/v7.0/entities

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [What is the Bing Entity Search API?](overview.md)

-## See also

-For more information about headers, parameters, market codes, response objects, errors and more, see the [Bing Entity Search API v7](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference) reference article.

-description: Learn details about the Bing Entity Search API and how to extract and search for entities and places from search queries.

-# What is Bing Entity Search API?

-The Bing Entity Search API sends a search query to Bing and gets results that include entities and places. Place results include restaurants, hotel, or other local businesses. Bing returns places if the query specifies the name of the local business or asks for a type of business (for example, restaurants near me). Bing returns entities if the query specifies well-known people, places (tourist attractions, states, countries/regions, etc.), or things.

-|Feature |Description |

-|||

-|[Real-time search suggestions](concepts/search-for-entities.md#suggest-search-terms-with-the-bing-autosuggest-api) | Provide search suggestions that can be displayed as a dropdown list as your users type. |

-| [Entity disambiguation](concepts/search-for-entities.md#the-bing-entity-search-api-response) | Get multiple entities for queries with multiple possible meanings. |

-| [Find places](concepts/search-for-entities.md#find-places) | Search for and return information on local businesses and entities |

-## Workflow

-The Bing Entity Search API is a RESTful web service, making it easy to call from any programming language that can make HTTP requests and parse JSON. You can use the service using either the REST API, or the SDK.

-1. Create an [Azure AI services API account](../cognitive-services-apis-create-account.md) with access to the Bing Search APIs. If you don't have an Azure subscription, you can [create an account](https://azure.microsoft.com/free/cognitive-services/) for free.

-2. Send a request to the API, with a valid search query.

-3. Process the API response by parsing the returned JSON message.

-## Next steps

-* Try the [interactive demo](https://azure.microsoft.com/services/cognitive-services/Bing-entity-search-api/) for the Bing Entity Search API.

-* To get started quickly with your first request, try a [Quickstart](quickstarts/csharp.md).

-* The [Bing Entity Search API v7](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference) reference section.

-* The [Bing Use and Display Requirements](../bing-web-search/use-display-requirements.md) specify acceptable uses of the content and information gained through the Bing search APIs.

-* Visit the [Bing Search API hub page](../bing-web-search/overview.md) to explore the other available APIs.

-description: The Entity Search API offers client libraries that makes it easy to integrate search capabilities into your applications. Use this quickstart to start sending search requests, and get back results.

-zone_pivot_groups: programming-languages-set-ten

-# Quickstart: Use the Bing Entity Search client library

-description: "Use this quickstart to send a request to the Bing Entity Search REST API using C#, and receive a JSON response."

-# Quickstart: Send a search request to the Bing Entity Search REST API using C#

-Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple C# application sends a news search query to the API, and displays the response. The source code for this application is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/dotnet/Search/BingEntitySearchv7.cs).

-Although this application is written in C#, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-## Create and initialize a project

-1. Create a new C# console solution in Visual Studio.

-1. Add the [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) NuGet package.

- 1. Right-click your project in **Solution Explorer**.

- 2. Select **Manage NuGet Packages**.

- 3. Search for and select *Newtonsoft.Json*, and then install the package.

-1. Then, add the following namespaces into the main code file:

-

- ```csharp

- using Newtonsoft.Json;

- using System;

- using System.Net.Http;

- using System.Text;

- ```

-2. Create a new class, and add variables for the API endpoint, your subscription key, and the query you want to search. You can use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```csharp

- namespace EntitySearchSample

- {

- class Program

- {

- static string host = "https://api.bing.microsoft.com";

- static string path = "/v7.0/search";

-

- static string market = "en-US";

-

- // NOTE: Replace this example key with a valid subscription key.

- static string key = "ENTER YOUR KEY HERE";

-

- static string query = "italian restaurant near me";

- //...

- }

- }

- ```

-## Send a request and get the API response

-1. Within the class, create a function called `Search()`. Within this function, create a new `HttpClient` object, and add your subscription key to the `Ocp-Apim-Subscription-Key` header.

-2. Construct the URI for your request by combining the host and path. Then, add your market and URL-encode your query.

-3. Await `client.GetAsync()` to get an HTTP response, and then store the JSON response by awaiting `ReadAsStringAsync()`.

-4. Format the JSON string with `JsonConvert.DeserializeObject()` and print it to the console.

- ```csharp

- async static void Search()

- {

- //...

- HttpClient client = new HttpClient();

- client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

- string uri = host + path + "?mkt=" + market + "&q=" + System.Net.WebUtility.UrlEncode(query);

- HttpResponseMessage response = await client.GetAsync(uri);

- string contentString = await response.Content.ReadAsStringAsync();

- dynamic parsedJson = JsonConvert.DeserializeObject(contentString);

- Console.WriteLine(parsedJson);

- }

- ```

-5. In the `Main()` method of your application, call the `Search()` function.

-

- ```csharp

- static void Main(string[] args)

- {

- Search();

- Console.ReadLine();

- }

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "italian restaurant near me",

- "askUserForLocation": true

- },

- "places": {

- "value": [

- {

- "_type": "LocalBusiness",

- "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "https://www.contoso.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- {

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",

- "name": "Munson's Pickles and Preserves Farm",

- "url": "https://www.princi.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness",

- "Restaurant"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98101",

- "addressCountry": "US",

- "neighborhood": "Capitol Hill"

- },

- "telephone": "(800) 555-1212"

- },

-

- . . .

- ]

- }

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a single-page web app](../tutorial-bing-entities-search-single-page-app.md)

-* [What is the Bing Entity Search API?](../overview.md)

-* [Bing Entity Search API reference](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference).

-description: Use this quickstart to send a request to the Bing Entity Search REST API using Java, and receive a JSON response.

-# Quickstart: Send a search request to the Bing Entity Search REST API using Java

-Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple Java application sends a news search query to the API, and displays the response.

-Although this application is written in Java, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* The [Java Development Kit (JDK)](https://www.oracle.com/technetwork/java/javase/downloads/).

-* The [Gson library](https://github.com/google/gson).

-## Create and initialize a project

-1. Create a new Java project in your favorite IDE or editor, and import the following libraries:

- ```java

- import java.io.*;

- import java.net.*;

- import java.util.*;

- import javax.net.ssl.HttpsURLConnection;

- import com.google.gson.Gson;

- import com.google.gson.GsonBuilder;

- import com.google.gson.JsonObject;

- import com.google.gson.JsonParser;

- import com.google.gson.Gson;

- import com.google.gson.GsonBuilder;

- import com.google.gson.JsonObject;

- import com.google.gson.JsonParser;

- ```

-2. In a new class, create variables for the API endpoint, your subscription key, and a search query. You can use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```java

- public class EntitySearch {

- static String subscriptionKey = "ENTER KEY HERE";

- static String host = "https://api.bing.microsoft.com";

- static String path = "/v7.0/search";

- static String mkt = "en-US";

- static String query = "italian restaurant near me";

- //...

- ```

-## Construct a search request string

-1. Create a function called `search()` that returns a JSON `String`. url-encode your search query, and add it to a parameters string with `&q=`. Add your market to the parameter string with `?mkt=`.

-2. Create a URL object with your host, path, and parameters strings.

- ```java

- //...

- public static String search () throws Exception {

- String encoded_query = URLEncoder.encode (query, "UTF-8");

- String params = "?mkt=" + mkt + "&q=" + encoded_query;

- URL url = new URL (host + path + params);

- //...

- ```

-## Send a search request and receive a response

-1. In the `search()` function created above, create a new `HttpsURLConnection` object with `url.openCOnnection()`. Set the request method to `GET`, and add your subscription key to the `Ocp-Apim-Subscription-Key` header.

- ```java

- //...

- HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();

- connection.setRequestMethod("GET");

- connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);

- connection.setDoOutput(true);

- //...

- ```

-2. Create a new `StringBuilder`. Use a new `InputStreamReader` as a parameter when instantiating `BufferedReader` to read the API response.

- ```java

- //...

- StringBuilder response = new StringBuilder ();

- BufferedReader in = new BufferedReader(

- new InputStreamReader(connection.getInputStream()));

- //...

- ```

-3. Create a `String` object to store the response from the `BufferedReader`. Iterate through it, and append each line to the string. Then, close the reader and return the response.

- ```java

- String line;

- while ((line = in.readLine()) != null) {

- response.append(line);

- }

- in.close();

- return response.toString();

- ```

-## Format the JSON response

-1. Create a new function called `prettify` to format the JSON response. Create a new `JsonParser`, call `parse()` on the JSON text, and then store it as a JSON object.

-2. Use the Gson library to create a new `GsonBuilder()`, use `setPrettyPrinting().create()` to format the JSON, and then return it.

- ```java

- //...

- public static String prettify (String json_text) {

- JsonParser parser = new JsonParser();

- JsonObject json = parser.parse(json_text).getAsJsonObject();

- Gson gson = new GsonBuilder().setPrettyPrinting().create();

- return gson.toJson(json);

- }

- //...

- ```

-## Call the search function

- ```java

- public static void main(String[] args) {

- try {

- String response = search ();

- System.out.println (prettify (response));

- }

- catch (Exception e) {

- System.out.println (e);

- }

- }

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "italian restaurant near me",

- "askUserForLocation": true

- },

- "places": {

- "value": [

- {

- "_type": "LocalBusiness",

- "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "https://www.contoso.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- {

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",

- "name": "Munson's Pickles and Preserves Farm",

- "url": "https://www.princi.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness",

- "Restaurant"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98101",

- "addressCountry": "US",

- "neighborhood": "Capitol Hill"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- ]

- }

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a single-page web app](../tutorial-bing-entities-search-single-page-app.md)

-* [What is the Bing Entity Search API?](../overview.md)

-* [Bing Entity Search API reference](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference).

-description: Use this quickstart to send a request to the Bing Entity Search REST API using Node.js and receive a JSON response.

-# Quickstart: Send a search request to the Bing Entity Search REST API using Node.js

-Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple JavaScript application sends a news search query to the API, and displays the response. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/nodejs/Search/BingEntitySearchv7.js).

-Although this application is written in JavaScript, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* The latest version of [Node.js](https://nodejs.org/en/download/).

-* The [JavaScript Request Library](https://github.com/request/request).

-## Create and initialize the application

-1. Create a new JavaScript file in your favorite IDE or editor, and set the strictness and HTTPS requirements.

- ```javaScript

- 'use strict';

- let https = require ('https');

- ```

-2. Create variables for the API endpoint, your subscription key, and search query. You can use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```javascript

- let subscriptionKey = 'ENTER YOUR KEY HERE';

- let host = 'api.bing.microsoft.com';

- let path = '/v7.0/search';

-

- let mkt = 'en-US';

- let q = 'italian restaurant near me';

- ```

-3. Append your market and query parameters to a string called `query`. Be sure to url-encode your query with `encodeURI()`.

- ```javascript

- let query = '?mkt=' + mkt + '&q=' + encodeURI(q);

- ```

-## Handle and parse the response

-1. Define a function named `response_handler()` that takes an HTTP call, `response`, as a parameter.

-2. Within this function, define a variable to contain the body of the JSON response.

- ```javascript

- let response_handler = function (response) {

- let body = '';

- };

- ```

-3. Store the body of the response when the `data` flag is called.

- ```javascript

- response.on('data', function (d) {

- body += d;

- });

- ```

-4. When an `end` flag is signaled, parse the JSON, and print it.

- ```javascript

- response.on ('end', function () {

- let json = JSON.stringify(JSON.parse(body), null, ' ');

- console.log (json);

- });

- ```

-## Send a request

-1. Create a function called `Search()` to send a search request. In it, perform the following steps:

-2. Within this function, create a JSON object containing your request parameters. Use `Get` for the method, and add your host and path information. Add your subscription key to the `Ocp-Apim-Subscription-Key` header.

-3. Use `https.request()` to send the request with the response handler created previously, and your search parameters.

-

- ```javascript

- let Search = function () {

- let request_params = {

- method : 'GET',

- hostname : host,

- path : path + query,

- headers : {

- 'Ocp-Apim-Subscription-Key' : subscriptionKey,

- }

- };

-

- let req = https.request (request_params, response_handler);

- req.end ();

- }

- ```

-2. Call the `Search()` function.

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "italian restaurant near me",

- "askUserForLocation": true

- },

- "places": {

- "value": [

- {

- "_type": "LocalBusiness",

- "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "https://www.contoso.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- {

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",

- "name": "Munson's Pickles and Preserves Farm",

- "url": "https://www.princi.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness",

- "Restaurant"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98101",

- "addressCountry": "US",

- "neighborhood": "Capitol Hill"

- },

- "telephone": "(800) 555-1212"

- },

-

- . . .

- ]

- }

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a single-page web app](../tutorial-bing-entities-search-single-page-app.md)

-* [What is the Bing Entity Search API?](../overview.md)

-* [Bing Entity Search API reference](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference).

-description: Use this quickstart to send a request to the Bing Entity Search REST API using PHP, and receive a JSON response.

-# Quickstart: Send a search request to the Bing Entity Search REST API using PHP

-Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple PHP application sends a news search query to the API, and displays the response.

-Although this application is written in PHP, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* [PHP 5.6.x](https://php.net/downloads.php) or later

-## Search entities

-To run this application, follow these steps:

-1. Create a new PHP project in your favorite IDE.

-2. Add the code provided below.

-3. Replace the `key` value with an access key valid for your subscription.

-4. You can use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

-5. Run the program.

-```php

-<?php

-// NOTE: Be sure to uncomment the following line in your php.ini file.

-// ;extension=php_openssl.dll

-// **********************************************

-// *** Update or verify the following values. ***

-// **********************************************

-// Replace the subscriptionKey string value with your valid subscription key.

-$subscriptionKey = 'ENTER KEY HERE';

-$host = "https://api.bing.microsoft.com";

-$path = "/v7.0/search";

-$mkt = "en-US";

-$query = "italian restaurants near me";

-function search ($host, $path, $key, $mkt, $query) {

- $params = '?mkt=' . $mkt . '&q=' . urlencode ($query);

- $headers = "Ocp-Apim-Subscription-Key: $key\r\n";

- // NOTE: Use the key 'http' even if you are making an HTTPS request. See:

- // https://php.net/manual/en/function.stream-context-create.php

- $options = array (

- 'http' => array (

- 'header' => $headers,

- 'method' => 'GET'

- )

- );

- $context = stream_context_create ($options);

- $result = file_get_contents ($host . $path . $params, false, $context);

- return $result;

-}

-$result = search ($host, $path, $subscriptionKey, $mkt, $query);

-echo json_encode (json_decode ($result), JSON_PRETTY_PRINT);

-?>

-```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "italian restaurant near me",

- "askUserForLocation": true

- },

- "places": {

- "value": [

- {

- "_type": "LocalBusiness",

- "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "https://www.contoso.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- {

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",

- "name": "Munson's Pickles and Preserves Farm",

- "url": "https://www.princi.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness",

- "Restaurant"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98101",

- "addressCountry": "US",

- "neighborhood": "Capitol Hill"

- },

- "telephone": "(800) 555-1212"

- },

-

- . . .

- ]

- }

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a single-page web app](../tutorial-bing-entities-search-single-page-app.md)

-* [What is the Bing Entity Search API?](../overview.md)

-* [Bing Entity Search API reference](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference).

-description: Use this quickstart to send a request to the Bing Entity Search REST API using Python, and receive a JSON response.

-# Quickstart: Send a search request to the Bing Entity Search REST API using Python

-Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple Python application sends a news search query to the API, and displays the response. The source code for this sample is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/python/Search/BingEntitySearchv7.py).

-Although this application is written in Python, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* [Python](https://www.python.org/downloads/) 2.x or 3.x

-## Create and initialize the application

-1. Create a new Python file in your favorite IDE or editor, and add the following imports. Create variables for your subscription key, endpoint, market, and search query. You can use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

- ```python

- import http.client, urllib.parse

- import json

-

- subscriptionKey = 'ENTER YOUR KEY HERE'

- host = 'api.bing.microsoft.com'

- path = '/v7.0/search'

- mkt = 'en-US'

- query = 'italian restaurants near me'

- ```

-2. Create a request url by appending your market variable to the `?mkt=` parameter. Url-encode your query and append it to the `&q=` parameter.

-

- ```python

- params = '?mkt=' + mkt + '&q=' + urllib.parse.quote (query)

- ```

-## Send a request and get a response

-1. Create a function called `get_suggestions()`.

-2. In this function, add your subscription key to a dictionary with `Ocp-Apim-Subscription-Key` as a key.

-3. Use `http.client.HTTPSConnection()` to create an HTTPS client object. Send a `GET` request using `request()` with your path and parameters, and header information.

-4. Store the response with `getresponse()`, and return `response.read()`.

- ```python

- def get_suggestions ():

- headers = {'Ocp-Apim-Subscription-Key': subscriptionKey}

- conn = http.client.HTTPSConnection (host)

- conn.request ("GET", path + params, None, headers)

- response = conn.getresponse ()

- return response.read()

- ```

-5. Call `get_suggestions()`, and print the JSON response.

- ```python

- result = get_suggestions ()

- print (json.dumps(json.loads(result), indent=4))

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "italian restaurant near me",

- "askUserForLocation": true

- },

- "places": {

- "value": [

- {

- "_type": "LocalBusiness",

- "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "https://www.contoso.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- {

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",

- "name": "Munson's Pickles and Preserves Farm",

- "url": "https://www.princi.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness",

- "Restaurant"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98101",

- "addressCountry": "US",

- "neighborhood": "Capitol Hill"

- },

- "telephone": "(800) 555-1212"

- },

-

- . . .

- ]

- }

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a single-page web app](../tutorial-bing-entities-search-single-page-app.md)

-* [What is the Bing Entity Search API?](../overview.md)

-* [Bing Entity Search API reference](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference).

-description: Use this quickstart to send a request to the Bing Entity Search REST API using Ruby, and receive a JSON response.

-# Quickstart: Send a search request to the Bing Entity Search REST API using Ruby

-Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple Ruby application sends a news search query to the API, and displays the response. The source code for this application is available on [GitHub](https://github.com/Azure-Samples/cognitive-services-REST-api-samples/blob/master/ruby/Search/BingEntitySearchv7.rb).

-Although this application is written in Ruby, the API is a RESTful Web service compatible with most programming languages.

-## Prerequisites

-* [Ruby 2.4](https://www.ruby-lang.org/en/downloads/) or later.

-## Create and initialize the application

-1. In your favorite IDE or code editor, create a news Ruby file and import the following packages:

- ```ruby

- require 'net/https'

- require 'cgi'

- require 'json'

- ```

-2. Create variables for your API endpoint, News search URL, your subscription key, and search query. You can use the global endpoint in the following code, or use the [custom subdomain](../../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

-

- ```ruby

- host = 'https://api.bing.microsoft.com'

- path = '/v7.0/search'

-

- mkt = 'en-US'

- query = 'italian restaurants near me'

- ```

-## Format and make an API request

-1. Create the parameters string for your request by appending your market variable to the `?mkt=` parameter. Encode your query and append it to the `&q=` parameter. Combine your API host, path, and the parameters for your request, and cast them as a URI object.

- ```ruby

- params = '?mkt=' + mkt + '&q=' + CGI.escape(query)

- uri = URI (host + path + params)

- ```

-2. Use the variables from the last step to create the request. Add your subscription key to the `Ocp-Apim-Subscription-Key` header.

- ```ruby

- request = Net::HTTP::Get.new(uri)

- request['Ocp-Apim-Subscription-Key'] = subscriptionKey

- ```

-3. Send the request, and print the response.

- ```ruby

- response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|

- http.request (request)

- end

- puts JSON::pretty_generate (JSON (response.body))

- ```

-## Example JSON response

-A successful response is returned in JSON, as shown in the following example:

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "italian restaurant near me",

- "askUserForLocation": true

- },

- "places": {

- "value": [

- {

- "_type": "LocalBusiness",

- "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",

- "name": "Liberty's Delightful Sinful Bakery & Cafe",

- "url": "https://www.contoso.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98112",

- "addressCountry": "US",

- "neighborhood": "Madison Park"

- },

- "telephone": "(800) 555-1212"

- },

- . . .

- {

- "_type": "Restaurant",

- "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",

- "name": "Munson's Pickles and Preserves Farm",

- "url": "https://www.princi.com/",

- "entityPresentationInfo": {

- "entityScenario": "ListItem",

- "entityTypeHints": [

- "Place",

- "LocalBusiness",

- "Restaurant"

- ]

- },

- "address": {

- "addressLocality": "Seattle",

- "addressRegion": "WA",

- "postalCode": "98101",

- "addressCountry": "US",

- "neighborhood": "Capitol Hill"

- },

- "telephone": "(800) 555-1212"

- },

-

- . . .

- ]

- }

-}

-```

-## Next steps

-> [!div class="nextstepaction"]

-> [Build a single-page web app](../tutorial-bing-entities-search-single-page-app.md)

-* [What is the Bing Entity Search API?](../overview.md)

-* [Bing Entity Search API reference](/rest/api/cognitiveservices-bingsearch/bing-entities-api-v7-reference).

-description: Learn how to use ranking to display the answers that the Bing Entity Search API returns.

-# Using ranking to display entity search results

-Each entity search response includes a [RankingResponse](/rest/api/cognitiveservices/bing-web-api-v7-reference#rankingresponse) answer that specifies how you must display search results returned by the Bing Entity Search API. The ranking response groups results into pole, mainline, and sidebar content. The pole result is the most important or prominent result and should be displayed first. If you do not display the remaining results in a traditional mainline and sidebar format, you must provide the mainline content higher visibility than the sidebar content.

-

-Within each group, the [Items](/rest/api/cognitiveservices/bing-web-api-v7-reference#rankinggroup-items) array identifies the order that the content must appear in. Each item provides two ways to identify the result within an answer.

-

-|Field | Description |

-|||

-|`answerType` and `resultIndex` | `answerType` identifies the answer (either Entity or Place) and `resultIndex` identifies a result within that answer (for example, an entity). The index starts at 0.|

-|`value` | `value` Contains an ID that matches the ID of either an answer or a result within the answer. Either the answer or the results contain the ID but not both. |

-

-Using the `answerType` and `resultIndex` is a two-step process. First, use `answerType` to identify the answer that contains the results to display. Then use `resultIndex` to index into that answer's results to get the result to display. (The `answerType` value is the name of the field in the [SearchResponse](/rest/api/cognitiveservices/bing-web-api-v7-reference#searchresponse) object.) If you're supposed to display all the answer's results together, the ranking response item doesn't include the `resultIndex` field.

-Using the ID requires you to match the ranking ID with the ID of an answer or one of its results. If an answer object includes an `id` field, display all the answer's results together. For example, if the `Entities` object includes the `id` field, display all the entities articles together. If the `Entities` object does not include the `id` field, then each entity contains an `id` field and the ranking response mixes the entities with the Places results.

-

-## Ranking response example

-The following shows an example [RankingResponse](/rest/api/cognitiveservices/bing-web-api-v7-reference#rankingresponse).

-

-```json

-{

- "_type": "SearchResponse",

- "queryContext": {

- "originalQuery": "Jimi Hendrix"

- },

- "entities": { ... },

- "rankingResponse": {

- "sidebar": {

- "items": [

- {

- "answerType": "Entities",

- "resultIndex": 0,

- "value": {

- "id": "https://www.bingapis.com/api/v7/#Entities.0"

- }

- },

- {

- "answerType": "Entities",

- "resultIndex": 1,

- "value": {

- "id": "https://www.bingapis.com/api/v7/#Entities.1"

- }

- }

- ]

- }

- }

-}

-```

-Based on this ranking response, the sidebar would display the two entity results related to Jimi Hendrix.

-## Next steps

-> [!div class="nextstepaction"]

-> [Create a single-page web app](tutorial-bing-entities-search-single-page-app.md)

-description: This tutorial shows how to use the Bing Entity Search API in a single-page Web application.

-# Tutorial: Single-page web app

-The Bing Entity Search API lets you search the Web for information about *entities* and *places.* You may request either kind of result, or both, in a given query. The definitions of places and entities are provided below.

-| Result | Description |

-|-|-|

-|Entities|Well-known people, places, and things that you find by name|

-|Places|Restaurants, hotels, and other local businesses that you find by name *or* by type (Italian restaurants)|

-In this tutorial, we build a single-page Web application that uses the Bing Entity Search API to display search results right in the page. The application includes HTML, CSS, and JavaScript components.

-The API lets you prioritize results by location. In a mobile app, you can ask the device for its own location. In a Web app, you can use the `getPosition()` function. But this call works only in secure contexts, and it may not provide a precise location. Also, the user may want to search for entities near a location other than their own.

-Our app therefore calls upon the Bing Maps service to obtain latitude and longitude from a user-entered location. The user can then enter the name of a landmark ("Space Needle") or a full or partial address ("New York City"), and the Bing Maps API provides the coordinates.

-<!-- Remove until we can replace with a sanitized version.

-![[Single-page Bing Entity Search app]](media/entity-search-spa-demo.png)

-> [!NOTE]

-> The JSON and HTTP headings at the bottom of the page reveal the JSON response and HTTP request information when clicked. These details are useful when exploring the service.

-The tutorial app illustrates how to:

-> [!div class="checklist"]

-> * Perform a Bing Entity Search API call in JavaScript

-> * Perform a Bing Maps `locationQuery` API call in JavaScript

-> * Pass search options to the API calls

-> * Display search results

-> * Handle the Bing client ID and API subscription keys

-> * Deal with any errors that might occur

-The tutorial page is entirely self-contained; it does not use any external frameworks, style sheets, or even image files. It uses only widely supported JavaScript language features and works with current versions of all major Web browsers.

-In this tutorial, we discuss only selected portions of the source code. The full source code is available [on a separate page](). Copy and paste this code into a text editor and save it as `bing.html`.

-> [!NOTE]

-> This tutorial is substantially similar to the [single-page Bing Web Search app tutorial](../bing-web-search/tutorial-bing-web-search-single-page-app.md), but deals only with entity search results.

-## Prerequisites

-To follow along with the tutorial, you need subscription keys for the Bing Search API, and Bing Maps API.

-* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/)

-* Once you have your Azure subscription:

- * <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesBingSearch-v7" title="Create a Bing Search resource" target="_blank">Create a Bing Search resource </a> in the Azure portal to get your key and endpoint. After it deploys, click **Go to resource**.

- * <a href="https://www.microsoft.com/maps/create-a-bing-maps-key.aspx" title="Create a Computer Vision resource" target="_blank">Create a Bing Maps resource </a> in the Azure portal to get your key and endpoint. After it deploys, click **Go to resource**.

-## App components

-Like any single-page Web app, the tutorial application includes three parts:

-> [!div class="checklist"]

-> * HTML - Defines the structure and content of the page

-> * CSS - Defines the appearance of the page

-> * JavaScript - Defines the behavior of the page

-This tutorial doesn't cover most of the HTML or CSS in detail, as they are straightforward.

-The HTML contains the search form in which the user enters a query and chooses search options. The form is connected to the JavaScript that actually performs the search by the `<form>` tag's `onsubmit` attribute:

-```html

-<form name="bing" onsubmit="return newBingEntitySearch(this)">

-```

-The `onsubmit` handler returns `false`, which keeps the form from being submitted to a server. The JavaScript code actually does the work of collecting the necessary information from the form and performing the search.

-The search is done in two phases. First, if the user has entered a location restriction, a Bing Maps query is done to convert it into coordinates. The callback for this query then kicks off the Bing Entity Search query.

-The HTML also contains the divisions (HTML `<div>` tags) where the search results appear.

-## Managing subscription keys

-> [!NOTE]

-> This app requires subscription keys for both the Bing Search API and the Bing Maps API.

-To avoid having to include the Bing Search and Bing Maps API subscription keys in the code, we use the browser's persistent storage to store them. If either key has not been stored, we prompt for it and store it for later use. If the key is later rejected by the API, we invalidate the stored key so the user is asked for it upon their next search.

-We define `storeValue` and `retrieveValue` functions that use either the `localStorage` object (if the browser supports it) or a cookie. Our `getSubscriptionKey()` function uses these functions to store and retrieve the user's key. You can use the global endpoint below, or the [custom subdomain](../../ai-services/cognitive-services-custom-subdomains.md) endpoint displayed in the Azure portal for your resource.

-```javascript

-// cookie names for data we store

-SEARCH_API_KEY_COOKIE = "bing-search-api-key";

-MAPS_API_KEY_COOKIE = "bing-maps-api-key";

-CLIENT_ID_COOKIE = "bing-search-client-id";

-// API endpoints

-SEARCH_ENDPOINT = "https://api.cognitive.microsoft.com/bing/v7.0/entities";

-MAPS_ENDPOINT = "https://dev.virtualearth.net/REST/v1/Locations";

-// ... omitted definitions of storeValue() and retrieveValue()

-// get stored API subscription key, or prompt if it's not found

-function getSubscriptionKey(cookie_name, key_length, api_name) {

- var key = retrieveValue(cookie_name);

- while (key.length !== key_length) {

- key = prompt("Enter " + api_name + " API subscription key:", "").trim();

- }

- // always set the cookie in order to update the expiration date

- storeValue(cookie_name, key);

- return key;

-}

-function getMapsSubscriptionKey() {

- return getSubscriptionKey(MAPS_API_KEY_COOKIE, 64, "Bing Maps");

-}

-function getSearchSubscriptionKey() {

- return getSubscriptionKey(SEARCH_API_KEY_COOKIE, 32, "Bing Search");

-}

-```

-The HTML `<body>` tag includes an `onload` attribute that calls `getSearchSubscriptionKey()` and `getMapsSubscriptionKey()` when the page has finished loading. These calls serve to immediately prompt the user for their keys if they haven't yet entered them.

-```html

-<body onload="document.forms.bing.query.focus(); getSearchSubscriptionKey(); getMapsSubscriptionKey();">

-```

-## Selecting search options

-![[Bing Entity Search form]](media/entity-search-spa-form.png)

-The HTML form includes the following controls:

-| Control | Description |

-|-|-|

-|`where`|A drop-down menu for selecting the market (location and language) used for the search.|

-|`query`|The text field in which to enter the search terms.|

-|`safe`|A checkbox indicating whether SafeSearch is turned on (restricts "adult" results)|

-|`what`|A menu for choosing to search for entities, places, or both.|

-|`mapquery`|The text field in which the user may enter a full or partial address, a landmark, etc. to help Bing Entity Search return more relevant results.|

-> [!NOTE]

-> Places results are currently available only in the United States. The `where` and `what` menus have code to enforce this restriction. If you choose a non-US market while Places is selected in the `what` menu, `what` changes to Anything. If you choose Places while a non-US market is selected in the `where` menu, `where` changes to the US.

-Our JavaScript function `bingSearchOptions()` converts these fields to a partial query string for the Bing Search API.

-```javascript

-// build query options from the HTML form

-function bingSearchOptions(form) {

- var options = [];

- options.push("mkt=" + form.where.value);

- options.push("SafeSearch=" + (form.safe.checked ? "strict" : "off"));

- if (form.what.selectedIndex) options.push("responseFilter=" + form.what.value);

- return options.join("&");

-}

-```

-For example, the SafeSearch feature can be `strict`, `moderate`, or `off`, with `moderate` being the default. But our form uses a checkbox, which has only two states. The JavaScript code converts this setting to either `strict` or `off` (we don't use `moderate`).

-The `mapquery` field isn't handled in `bingSearchOptions()` because it is used for the Bing Maps location query, not for Bing Entity Search.

-## Obtaining a location

-The Bing Maps API offers a [`locationQuery` method](//msdn.microsoft.com/library/ff701711.aspx), which we use to find the latitude and longitude of the location the user enters. These coordinates are then passed to the Bing Entity Search API with the user's request. The search results prioritize entities and places that are close to the specified location.

-We can't access the Bing Maps API using an ordinary `XMLHttpRequest` query in a Web app because the service does not support cross-origin queries. Fortunately, it supports JSONP (the "P" is for "padded"). A JSONP response is an ordinary JSON response wrapped in a function call. The request is made by inserting using a `<script>` tag into the document. (Loading scripts is not subject to browser security policies.)

-The `bingMapsLocate()` function creates and inserts the `<script>` tag for the query. The `jsonp=bingMapsCallback` segment of the query string specifies the name of the function to be called with the response.

-```javascript

-function bingMapsLocate(where) {

- where = where.trim();

- var url = MAPS_ENDPOINT + "?q=" + encodeURIComponent(where) +

- "&jsonp=bingMapsCallback&maxResults=1&key=" + getMapsSubscriptionKey();

- var script = document.getElementById("bingMapsResult")

- if (script) script.parentElement.removeChild(script);

- // global variable holds reference to timer that will complete the search if the maps query fails

- timer = setTimeout(function() {

- timer = null;

- var form = document.forms.bing;

- bingEntitySearch(form.query.value, "", bingSearchOptions(form), getSearchSubscriptionKey());

- }, 5000);

- script = document.createElement("script");

- script.setAttribute("type", "text/javascript");

- script.setAttribute("id", "bingMapsResult");

- script.setAttribute("src", url);

- script.setAttribute("onerror", "BingMapsCallback(null)");

- document.body.appendChild(script);

- return false;

-}

-```

-> [!NOTE]

-> If the Bing Maps API does not respond, the `bingMapsCallBack()` function is never called. Ordinarily, that would mean that `bingEntitySearch()` isn't called, and the entity search results do not appear. To avoid this scenario, `bingMapsLocate()` also sets a timer to call `bingEntitySearch()` after five seconds. There is logic in the callback function to avoid performing the entity search twice.

-When the query completes, the `bingMapsCallback()` function is called, as requested.

-```javascript

-function bingMapsCallback(response) {

- if (timer) { // we beat the timer; stop it from firing

- clearTimeout(timer);

- timer = null;

- } else { // the timer beat us; don't do anything

- return;

- }

- var location = "";

- var name = "";

- var radius = 1000;

- if (response) {

- try {

- if (response.statusCode === 401) {

- invalidateMapsKey();

- } else if (response.statusCode === 200) {

- var resource = response.resourceSets[0].resources[0];

- var coords = resource.point.coordinates;

- name = resource.name;

- // the radius is the largest of the distances between the location and the corners

- // of its bounding box (in case it's not in the center) with a minimum of 1 km

- try {

- var bbox = resource.bbox;

- radius = Math.max(haversineDistance(bbox[0], bbox[1], coords[0], coords[1]),

- haversineDistance(coords[0], coords[1], bbox[2], bbox[1]),

- haversineDistance(bbox[0], bbox[3], coords[0], coords[1]),

- haversineDistance(coords[0], coords[1], bbox[2], bbox[3]), 1000);

- } catch(e) { }

- var location = "lat:" + coords[0] + ";long:" + coords[1] + ";re:" + Math.round(radius);

- }

- }

- catch (e) { } // response is unexpected. this isn't fatal, so just don't provide location

- }

- var form = document.forms.bing;

- if (name) form.mapquery.value = name;

- bingEntitySearch(form.query.value, location, bingSearchOptions(form), getSearchSubscriptionKey());

-}

-```

-Along with latitude and longitude, the Bing Entity Search query requires a *radius* that indicates the precision of the location information. We calculate the radius using the *bounding box* provided in the Bing Maps response. The bounding box is a rectangle that surrounds the entire location. For example, if the user enters `NYC`, the result contains roughly central coordinates of New York City and a bounding box that encompasses the city.

-We first calculate the distances from the primary coordinates to each of the four corners of the bounding box using the function `haversineDistance()` (not shown). We use the largest of these four distances as the radius. The minimum radius is a kilometer. This value is also used as a default if no bounding box is provided in the response.

-Having obtained the coordinates and the radius, we then call `bingEntitySearch()` to perform the actual search.

-## Performing the search

-Given the query, a location, an options string, and the API key, the `BingEntitySearch()` function makes the Bing Entity Search request.

-```javascript

-// perform a search given query, location, options string, and API keys

-function bingEntitySearch(query, latlong, options, key) {

- // scroll to top of window

- window.scrollTo(0, 0);

- if (!query.trim().length) return false; // empty query, do nothing

- showDiv("noresults", "Working. Please wait.");

- hideDivs("pole", "mainline", "sidebar", "_json", "_http", "error");

- var request = new XMLHttpRequest();

- var queryurl = SEARCH_ENDPOINT + "?q=" + encodeURIComponent(query) + "&" + options;

- // open the request

- try {

- request.open("GET", queryurl);

- }

- catch (e) {

- renderErrorMessage("Bad request (invalid URL)\n" + queryurl);

- return false;

- }

- // add request headers

- request.setRequestHeader("Ocp-Apim-Subscription-Key", key);

- request.setRequestHeader("Accept", "application/json");

- var clientid = retrieveValue(CLIENT_ID_COOKIE);

- if (clientid) request.setRequestHeader("X-MSEdge-ClientID", clientid);

- if (latlong) request.setRequestHeader("X-Search-Location", latlong);

- // event handler for successful response

- request.addEventListener("load", handleBingResponse);

-

- // event handler for erorrs

- request.addEventListener("error", function() {

- renderErrorMessage("Error completing request");

- });

- // event handler for aborted request

- request.addEventListener("abort", function() {

- renderErrorMessage("Request aborted");

- });

- // send the request

- request.send();

- return false;

-}

-```

-Upon successful completion of the HTTP request, JavaScript calls our `load` event handler, the `handleBingResponse()` function, to handle a successful HTTP GET request to the API.

-```javascript

-// handle Bing search request results

-function handleBingResponse() {

- hideDivs("noresults");

- var json = this.responseText.trim();

- var jsobj = {};

- // try to parse JSON results

- try {

- if (json.length) jsobj = JSON.parse(json);

- } catch(e) {

- renderErrorMessage("Invalid JSON response");

- }

- // show raw JSON and HTTP request

- showDiv("json", preFormat(JSON.stringify(jsobj, null, 2)));

- showDiv("http", preFormat("GET " + this.responseURL + "\n\nStatus: " + this.status + " " +

- this.statusText + "\n" + this.getAllResponseHeaders()));

- // if HTTP response is 200 OK, try to render search results

- if (this.status === 200) {

- var clientid = this.getResponseHeader("X-MSEdge-ClientID");

- if (clientid) retrieveValue(CLIENT_ID_COOKIE, clientid);

- if (json.length) {

- if (jsobj._type === "SearchResponse") {

- renderSearchResults(jsobj);

- } else {

- renderErrorMessage("No search results in JSON response");

- }

- } else {

- renderErrorMessage("Empty response (are you sending too many requests too quickly?)");

- }

- if (divHidden("pole") && divHidden("mainline") && divHidden("sidebar"))

- showDiv("noresults", "No results.<p><small>Looking for restaurants or other local businesses? Those currently areen't supported outside the US.</small>");

- }

- // Any other HTTP status is an error

- else {

- // 401 is unauthorized; force re-prompt for API key for next request

- if (this.status === 401) invalidateSearchKey();

- // some error responses don't have a top-level errors object, so gin one up

- var errors = jsobj.errors || [jsobj];

- var errmsg = [];

- // display HTTP status code

- errmsg.push("HTTP Status " + this.status + " " + this.statusText + "\n");

- // add all fields from all error responses

- for (var i = 0; i < errors.length; i++) {

- if (i) errmsg.push("\n");

- for (var k in errors[i]) errmsg.push(k + ": " + errors[i][k]);

- }

- // also display Bing Trace ID if it isn't blocked by CORS

- var traceid = this.getResponseHeader("BingAPIs-TraceId");

- if (traceid) errmsg.push("\nTrace ID " + traceid);

- // and display the error message

- renderErrorMessage(errmsg.join("\n"));

- }

-}

-```

-> [!IMPORTANT]

-> A successful HTTP request does *not* necessarily mean that the search itself succeeded. If an error occurs in the search operation, the Bing Entity Search API returns a non-200 HTTP status code and includes error information in the JSON response. Additionally, if the request was rate-limited, the API returns an empty response.

-Much of the code in both of the preceding functions is dedicated to error handling. Errors may occur at the following stages:

-|Stage|Potential error(s)|Handled by|

-|-|-|-|

-|Building JavaScript request object|Invalid URL|`try`/`catch` block|

-|Making the request|Network errors, aborted connections|`error` and `abort` event handlers|

-|Performing the search|Invalid request, invalid JSON, rate limits|tests in `load` event handler|

-Errors are handled by calling `renderErrorMessage()` with any details known about the error. If the response passes the full gauntlet of error tests, we call `renderSearchResults()` to display the search results in the page.

-## Displaying search results

-The Bing Entity Search API [requires you to display results in a specified order](../bing-web-search/use-display-requirements.md). Since the API may return two different kinds of responses, it is not enough to iterate through the top level `Entities` or `Places` collection in the JSON response and display those results. (If you want only one type of result, use the `responseFilter` query parameter.)

-Instead, we use the `rankingResponse` collection in the search results to order the results for display. This object refers to items in the `Entitiess` and/or `Places` collections.

-`rankingResponse` may contain up to three collections of search results, designated `pole`, `mainline`, and `sidebar`.

-`pole`, if present, is the most relevant search result and should be displayed prominently. `mainline` refers to the bulk of the search results. Mainline results should be displayed immediately after `pole` (or first, if `pole` is not present).

-Finally. `sidebar` refers to auxiliary search results. They may be displayed in an actual sidebar or simply after the mainline results. We have chosen the latter for our tutorial app.

-Each item in a `rankingResponse` collection refers to the actual search result items in two different, but equivalent, ways.

-| Item | Description |

-|-|-|

-|`id`|The `id` looks like a URL, but should not be used for links. The `id` type of a ranking result matches the `id` of either a search result item in an answer collection, *or* an entire answer collection (such as `Entities`).

-|`answerType`<br>`resultIndex`|The `answerType` refers to the top-level answer collection that contains the result (for example, `Entities`). The `resultIndex` refers to the result's index within that collection. If `resultIndex` is omitted, the ranking result refers to the entire collection.

-> [!NOTE]

-> For more information on this part of the search response, see [Rank Results](rank-results.md).

-You may use whichever method of locating the referenced search result item is most convenient for your application. In our tutorial code, we use the `answerType` and `resultIndex` to locate each search result.

-Finally, it's time to look at our function `renderSearchResults()`. This function iterates over the three `rankingResponse` collections that represent the three sections of the search results. For each section, we call `renderResultsItems()` to render the results for that section.

-```javascript

-// render the search results given the parsed JSON response

-function renderSearchResults(results) {

- // if spelling was corrected, update search field

- if (results.queryContext.alteredQuery)

- document.forms.bing.query.value = results.queryContext.alteredQuery;

- // for each possible section, render the results from that section

- for (section in {pole: 0, mainline: 0, sidebar: 0}) {

- if (results.rankingResponse[section])

- showDiv(section, renderResultsItems(section, results));

- }

-}

-```

-## Rendering result items

-In our JavaScript code is an object, `searchItemRenderers`, that contains *renderers:* functions that generate HTML for each kind of search result.

-```javascript

-searchItemRenderers = {

- entities: function(item) { ... },

- places: function(item) { ... }

-}

-```

-A renderer function may accept the following parameters:

-| Parameter | Description |

-|-|-|

-|`item`|The JavaScript object containing the item's properties, such as its URL and its description.|

-|`index`|The index of the result item within its collection.|

-|`count`|The number of items in the search result item's collection.|

-The `index` and `count` parameters can be used to number results, to generate special HTML for the beginning or end of a collection, to insert line breaks after a certain number of items, and so on. If a renderer does not need this functionality, it does not need to accept these two parameters. In fact, we do not use them in the renderers for our tutorial app.

-Let's take a closer look at the `entities` renderer:

-```javascript

- entities: function(item) {

- var html = [];

- html.push("<p class='entity'>");

- if (item.image) {

- var img = item.image;

- if (img.hostPageUrl) html.push("<a href='" + img.hostPageUrl + "'>");

- html.push("<img src='" + img.thumbnailUrl + "' title='" + img.name + "' height=" + img.height + " width= " + img.width + ">");

- if (img.hostPageUrl) html.push("</a>");

- if (img.provider) {

- var provider = img.provider[0];

- html.push("<small>Image from ");

- if (provider.url) html.push("<a href='" + provider.url + "'>");

- html.push(provider.name ? provider.name : getHost(provider.url));

- if (provider.url) html.push("</a>");

- html.push("</small>");

- }

- }

- html.push("<p>");

- if (item.entityPresentationInfo) {

- var pi = item.entityPresentationInfo;

- if (pi.entityTypeHints || pi.entityTypeDisplayHint) {

- html.push("<i>");

- if (pi.entityTypeDisplayHint) html.push(pi.entityTypeDisplayHint);

- else if (pi.entityTypeHints) html.push(pi.entityTypeHints.join("/"));

- html.push("</i> - ");

- }

- }

- html.push(item.description);

- if (item.webSearchUrl) html.push("&nbsp;<a href='" + item.webSearchUrl + "'>More</a>")

- if (item.contractualRules) {

- html.push("<p><small>");

- var rules = [];

- for (var i = 0; i < item.contractualRules.length; i++) {

- var rule = item.contractualRules[i];

- var link = [];

- if (rule.license) rule = rule.license;

- if (rule.url) link.push("<a href='" + rule.url + "'>");

- link.push(rule.name || rule.text || rule.targetPropertyName + " source");

- if (rule.url) link.push("</a>");

- rules.push(link.join(""));

- }

- html.push("License: " + rules.join(" - "));

- html.push("</small>");

- }

- return html.join("");

- }, // places renderer omitted

-```

-Our entity renderer function:

-> [!div class="checklist"]

-> * Builds the HTML `<img>` tag to display the image thumbnail, if any.

-> * Builds the HTML `<a>` tag that links to the page that contains the image.

-> * Builds the description that displays information about the image and the site it's on.

-> * Incorporates the entity's classification using the display hints, if any.

-> * Includes a link to a Bing search to get more information about the entity.

-> * Displays any licensing or attribution information required by data sources.

-## Persisting client ID

-Responses from the Bing search APIs may include a `X-MSEdge-ClientID` header that should be sent back to the API with successive requests. If multiple Bing Search APIs are being used, the same client ID should be used with all of them, if possible.

-Providing the `X-MSEdge-ClientID` header allows the Bing APIs to associate all of a user's searches, which have two important benefits.

-First, it allows the Bing search engine to apply past context to searches to find results that better satisfy the user. If a user has previously searched for terms related to sailing, for example, a later search for "docks" might preferentially return information about places to dock a sailboat.

-Second, Bing may randomly select users to experience new features before they are made widely available. Providing the same client ID with each request ensures that users that have been chosen to see a feature always see it. Without the client ID, the user might see a feature appear and disappear, seemingly at random, in their search results.

-Browser security policies (CORS) may prevent the `X-MSEdge-ClientID` header from being available to JavaScript. This limitation occurs when the search response has a different origin from the page that requested it. In a production environment, you should address this policy by hosting a server-side script that does the API call on the same domain as the Web page. Since the script has the same origin as the Web page, the `X-MSEdge-ClientID` header is then available to JavaScript.

-> [!NOTE]

-> In a production Web application, you should perform the request server-side anyway. Otherwise, your Bing Search API key must be included in the Web page, where it is available to anyone who views source. You are billed for all usage under your API subscription key, even requests made by unauthorized parties, so it is important not to expose your key.

-For development purposes, you can make the Bing Web Search API request through a CORS proxy. The response from such a proxy has an `Access-Control-Expose-Headers` header that allow lists response headers and makes them available to JavaScript.

-It's easy to install a CORS proxy to allow our tutorial app to access the client ID header. First, if you don't already have it, [install Node.js](https://nodejs.org/en/download/). Then issue the following command in a command window:

-```console

-npm install -g cors-proxy-server

-```

-Next, change the Bing Web Search endpoint in the HTML file to:\

-`http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/search`

-Finally, start the CORS proxy with the following command:

-```console

-cors-proxy-server

-```

-Leave the command window open while you use the tutorial app; closing the window stops the proxy. In the expandable HTTP Headers section below the search results, you can now see the `X-MSEdge-ClientID` header (among others) and verify that it is the same for each request.

-## Next steps

-> [!div class="nextstepaction"]

-> [Bing Entity Search API reference](/rest/api/cognitiveservices/bing-entities-api-v7-reference)

-> [!div class="nextstepaction"]

-> [Bing Maps API documentation](/bingmaps/)

-description: Find answers to commonly asked questions about concepts, code, and scenarios related to the Bing Image Search API.

-# Frequently asked questions (FAQ) about the Bing Image Search API

-Find answers to commonly asked questions about concepts, code, and scenarios related to the Bing Image Search API for Azure AI services on Azure.

-## Response headers in JavaScript

-The following headers may occur in responses from the Bing Image Search API.

-| Attribute | Description |

-| - | - |

-| `X-MSEdge-ClientID` |The unique ID that Bing has assigned to the user |

-| `BingAPIs-Market` |The market that was used to fulfill the request |

-| `BingAPIs-TraceId` |The log entry on the Bing API server for this request (for support) |

-It is particularly important to persist the client ID and return it with subsequent requests. When you do this, the search will use past context in ranking search results and also provide a consistent user experience.

-However, when you call the Bing Image Search API from JavaScript, your browser's built-in security features (CORS) might prevent you from accessing the values of these headers.

-To gain access to the headers, you can make the Bing Image Search API request through a CORS proxy. The response from such a proxy has an `Access-Control-Expose-Headers` header that filters response headers and makes them available to JavaScript.

-It's easy to install a CORS proxy to allow our [tutorial app](tutorial-bing-image-search-single-page-app.md) to access the optional client headers. First, if you don't already have it, [install Node.js](https://nodejs.org/en/download/). Then enter the following command at a command prompt.

-```console

-npm install -g cors-proxy-server

-```

-Next, change the Bing Image Search API endpoint in the HTML file to:\

-`http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/search`

-Finally, start the CORS proxy with the following command:

-```console

-cors-proxy-server

-```

-Leave the command window open while you use the tutorial app; closing the window stops the proxy. In the expandable HTTP Headers section below the search results, you can now see the `X-MSEdge-ClientID` header (among others) and verify that it is the same for each request.

-## Response headers in production

-The CORS proxy approach described in the previous answer is appropriate for development, testing, and learning.

-In a production environment, however, you should host a server-side script on the same domain as the Web page that uses the Bing Web Search API. This script should actually do the API calls upon request from the Web page JavaScript and pass all results, including headers, back to the client. Since the two resources (page and script) share an origin, CORS does not come into play and the special headers are accessible to the JavaScript on the Web page.

-This approach also protects your API key from exposure to the public, since only the server-side script needs it. The script can use another method (such as the HTTP referrer) to make sure the request is authorized.

-## Next steps

-Is your question about a missing feature or functionality? Consider requesting or voting for it using the [feedback tool](https://feedback.azure.com/d365community/forum/09041fae-0b25-ec11-b6e6-000d3a4f0858).

-## See also

- [Stack Overflow: Azure AI services](https://stackoverflow.com/questions/tagged/bing-api)

-description: This upgrade guide describes changes between version 5 and version 7 of the Bing Image Search API. Use this guide to help you identify the parts of your application that you need to update to use version 7.

-# Bing Image Search API v7 upgrade guide

-This upgrade guide identifies the changes between version 5 and version 7 of the Bing Image Search API. Use this guide to help you identify the parts of your application that you need to update to use version 7.

-## Breaking changes

-### Endpoints

-### Error response objects and error codes

- - `subCode`&mdash;Partitions the error code into discrete buckets, if possible

- - `moreDetails`&mdash;Additional information about the error described in the `message` field

-|Code|SubCode|Description

-|-|-|-

-|ServerError|UnexpectedError<br/>ResourceError<br/>NotImplemented|Bing returns ServerError whenever any of the sub-code conditions occur. The response includes these errors if the HTTP status code is 500.

-|InvalidRequest|ParameterMissing<br/>ParameterInvalidValue<br/>HttpNotAllowed<br/>Blocked|Bing returns InvalidRequest whenever any part of the request is not valid. For example, a required parameter is missing or a parameter value is not valid.<br/><br/>If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400.<br/><br/>If the error is HttpNotAllowed, the HTTP status code 410.

-|RateLimitExceeded||Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.<br/><br/>Bing returns HTTP status code 429 if you exceeded QPS and 403 if you exceeded QPM.

-|InvalidAuthorization|AuthorizationMissing<br/>AuthorizationRedundancy|Bing returns InvalidAuthorization when Bing cannot authenticate the caller. For example, the `Ocp-Apim-Subscription-Key` header is missing or the subscription key is not valid.<br/><br/>Redundancy occurs if you specify more than one authentication method.<br/><br/>If the error is InvalidAuthorization, the HTTP status code is 401.

-|InsufficientAuthorization|AuthorizationDisabled<br/>AuthorizationExpired|Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. This can occur if the subscription key has been disabled or has expired. <br/><br/>If the error is InsufficientAuthorization, the HTTP status code is 403.

-|Version 5 code|Version 7 code.subCode

-|-|-

-|RequestParameterMissing|InvalidRequest.ParameterMissing

-RequestParameterInvalidValue|InvalidRequest.ParameterInvalidValue

-ResourceAccessDenied|InsufficientAuthorization

-ExceededVolume|RateLimitExceeded

-ExceededQpsLimit|RateLimitExceeded

-Disabled|InsufficientAuthorization.AuthorizationDisabled

-UnexpectedError|ServerError.UnexpectedError

-DataSourceErrors|ServerError.ResourceError

-AuthorizationMissing|InvalidAuthorization.AuthorizationMissing

-HttpNotAllowed|InvalidRequest.HttpNotAllowed

-UserAgentMissing|InvalidRequest.ParameterMissing

-NotImplemented|ServerError.NotImplemented

-InvalidAuthorization|InvalidAuthorization

-InvalidAuthorizationMethod|InvalidAuthorization

-MultipleAuthorizationMethod|InvalidAuthorization.AuthorizationRedundancy

-ExpiredAuthorizationToken|InsufficientAuthorization.AuthorizationExpired

-InsufficientScope|InsufficientAuthorization

-Blocked|InvalidRequest.Blocked

-### Query parameters

-### Image insights changes

- - [insightsToken](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#insightstoken)

- - [modules](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference)

- - [imgUrl](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imgurl)

- - [cab](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#cab)

- - [cal](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#cal)

- - [car](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#car)

- - [cat](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#cat)

- - [ct](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#ct)

- - Changed the type of the `relatedCollections` field from `ImageGallery[]` to [RelatedCollectionsModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#relatedcollectionsmodule).

- - Changed the type of the `pagesIncluding` field from `Image[]` to [ImagesModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imagesmodule).

- - Changed the type of the `relatedSearches` field from `Query[]` to [RelatedSearchesModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#relatedsearchesmodule).

- - Changed the type of the `recipes` field from `Recipe[]` to [RecipesModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#recipesmodule).

- - Changed the type of the `visuallySimilarImages` field from `Image[]` to [ImagesModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imagesmodule).

- - Changed the type of the `visuallySimilarProducts` field from `ProductSummaryImage[]` to [ImagesModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imagesmodule).

- - Removed the `ProductSummaryImage` object and moved the product-related fields into the [Image](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#image) object. The `Image` object includes the product-related fields only when the image is included as part of visually similar products in an image insight response.

- - Changed the type of the `recognizedEntityGroups` field from `RecognizedEntityGroup[]` to [RecognizedEntitiesModule](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#recognizedentitiesmodule).

-### Images answer

-## Non-breaking changes

-### Query parameters

-### Object changes

-description: Use the Bing Image Search API to search for and get relevant images from the web.

-# Get images from the web with the Bing Image Search API

-When you use the Bing Image Search REST API, you can get images from the web that are related to your search term by sending the following GET request:

-```http

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=sailing+dinghies&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-Use the [q](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#query) query parameter for your url-encoded search term. For example, if you enter *sailing dinghies*, set `q` to `sailing+dinghies` or `sailing%20dinghies`.

-> [!IMPORTANT]

-> * All requests must be made from a server, and not from a client.

-> * If it's your first time calling any of the Bing search APIs, don't include the client ID header. Only include the client ID if you've previously called a Bing API that returned a client ID for the user and device combination.

-## Get images from a specific web domain

-To get images from a specific domain, use the [site:](/previous-versions/bing/search/ff795613(v=msdn.10)) query operator.

-```http

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=sailing+dinghies+site:contososailing.com&mkt=en-us HTTP/1.1

-```

-> [!NOTE]

-> Responses to queries using the `site:` operator might include adult content regardless of the [safeSearch](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#safesearch) setting. Only use `site:` if you're aware of the content on the domain.

-## Filter images

- By default, the Image Search API returns all images that are relevant to the query. If you want to filter the images that Bing returns (for example, to return only images with a transparent background or specific size), use the following query parameters:

-* [aspect](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#aspect)ΓÇöFilter images by aspect ratio (for example, standard or wide screen images).

-* [color](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#color)ΓÇöFilter images by dominant color or black and white.

-* [freshness](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#freshness)ΓÇöFilter images by age (for example, images discovered by Bing in the past week).

-* [height](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#height), [width](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#width)ΓÇöFilter images by width and height.

-* [imageContent](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imagecontent)ΓÇöFilter images by content (for example, images that show only a person's face).

-* [imageType](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imagetype)ΓÇöFilter images by type (for example, clip art, animated GIFs, or transparent backgrounds).

-* [license](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#license)ΓÇöFilter images by the type of license associated with the site.

-* [size](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#size)ΓÇöFilter images by size, such as small images up to 200x200 pixels.

-To get images from a specific domain, use the [site:](/previous-versions/bing/search/ff795613(v=msdn.10)) query operator.

-The following example shows how to get small images from ContosoSailing.com that Bing discovered in the past week.

-```http

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=sailing+dinghies+site:contososailing.com&size=small&freshness=week&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-## Bing Image Search response format

-The response message from Bing contains an [Images](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#images) answer that contains a list of images that Azure AI services determined to be relevant to the query. Each [Image](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#image) object in the list includes the following information about the image: the URL, its size, its dimensions, its encoding format, a URL to a thumbnail of the image, and the thumbnail's dimensions.

-> [!NOTE]

-> * Images must be displayed in the order provided in the response.

-> * Because URL formats and parameters are subject to change without notice, use all URLs as-is. You should not take dependencies on the URL format or parameters except where noted.

-```json

-{

- "name": "Rich Passage Sailing Dinghy",

- "webSearchUrl": "https:\/\/www.bing.com\/cr?IG=73118C8B4E3...",

- "thumbnailUrl": "https:\/\/tse1.mm.bing.net\/th?id=OIP.GNarK7m...",

- "datePublished": "2011-10-29T11:26:00",

- "contentUrl": "http:\/\/www.bing.com\/cr?IG=73118C8B4E3D4C3...",

- "hostPageUrl": "http:\/\/www.bing.com\/cr?IG=73118C8B4E3D4C3687...",

- "contentSize": "79239 B",

- "encodingFormat": "jpeg",

- "hostPageDisplayUrl": "en.contoso.org\/wiki\/File:Rich_Passage...",

- "width": 526,

- "height": 688,

- "thumbnail": {

- "width": 229,

- "height": 300

- },

- "imageInsightsToken": "ccid_GNarK7ma*mid_CCF85447ADA6...",

- "insightsSourcesSummary": {

- "shoppingSourcesCount": 0,

- "recipeSourcesCount": 0

- },

- "imageId": "CCF85447ADA6FFF9E96E7DF0B796F7A86E34593",

- "accentColor": "376094"

-},

-```

-When you call the Bing Image Search API, Bing returns a list of results. The list is a subset of the total number of results that are relevant to the query. The response's `totalEstimatedMatches` field contains an estimate of the number of images that are available to view. For details about how to page through the rest of the images, see [Paging Images](../../bing-web-search/paging-search-results.md).

-## Next steps

-If you haven't tried the Bing Image Search API before, try a [quickstart](../quickstarts/csharp.md). If you're looking for something more complex, try the tutorial to create a [single-page web app](../tutorial-bing-image-search-single-page-app.md).

-description: Learn about customizing the search queries you send to the Bing Image Search API.

-# Customize and suggest image search queries

-Use this article to learn how to customize queries and suggest search terms to send to the Bing Image Search API.

-## Suggest search terms

-If your app has a search box where search terms are entered, you can use the [Bing Autosuggest API](../../bing-autosuggest/get-suggested-search-terms.md) to improve the experience. The API can display suggested search terms in real time. The API returns suggested query strings based on partial search terms and Azure AI services.

-## Pivot the query

-If Bing can segment the original search query, the returned [Images](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#images) object contains `pivotSuggestions`. Pivot suggestions can be displayed as optional search terms to the user. For example, if the original query was *Microsoft Surface*, Bing might segment the query into *Microsoft* and *Surface* and provide suggested pivots for each. These suggestions can be displayed as optional query terms to the user.

-The following example shows the pivot suggestions for *Microsoft Surface*:

-```json

-{

- "_type": "Images",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=microsoft%20surface&FORM=OIIARP",

- "totalEstimatedMatches": 1000,

- "value": [...],

- "queryExpansions": [...],

- "pivotSuggestions": [{

- "pivot": "microsoft",

- "suggestions": [{

- "text": "Contoso Surface",

- "displayText": "Contoso",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=OtterBox+Surface&FORM=IRQBPS",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=Contoso...",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Contoso+Surface..."

- }

- },

- {

- "text": "Adatum Surface",

- "displayText": "Adatum",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Adatum+Surface&FORM=IRQBPS",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Adatum+Surface&pid=Ap..."

- }

- },

- ...

- ]

- },

- {

- "pivot": "surface",

- "suggestions": [{

- "text": "Microsoft Surface4",

- "displayText": "Surface4",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface...",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft..."

- }

- },

- {

- "text": "Microsoft Tablet",

- "displayText": "Tablet",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Tablet&FORM=IRQBPS",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Microsoft+Tablet..."

- }

- },

- ...

- ],

- "nextOffsetAddCount": 0

-}

-```

-The `pivotSuggestions` field contains the list of segments (pivots) that the original query was broken into. For each pivot, the response contains a list of [Query](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#query_obj) objects that contain suggested queries. The `text` field contains the suggested query. The `displayText` field contains the term that replaces the pivot in the original query. An example is Release Date of Surface.

-If the pivot query string is what the user is looking for, use the `text` and `thumbnail` fields to display the pivot query strings. Make the thumbnail and text clickable by using the `webSearchUrl` URL or the `searchLink` URL. Use `webSearchUrl` to send the user to the Bing search results. If you provide your own results page, use `searchLink`.

-<!-- Need a sanitized version of the image

-The following shows an example of the pivot queries.

-

-## Expand the query

-If Bing can expand the query to narrow the original search, the [Images](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#images) object contains the `queryExpansions` field. For example, if the query was *Microsoft Surface*, the expanded queries might be:

-The following example shows the expanded queries for *Microsoft Surface*.

-```json

-{

- "_type": "Images",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=microsoft%20surface...",

- "totalEstimatedMatches": 1000,

- "value": [...],

- "queryExpansions": [{

- "text": "Microsoft Surface Pro 3",

- "displayText": "Pro 3",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+Pro+3...",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=Microsoft...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+Pro+3..."

- }

- },

- {

- "text": "Microsoft Surface RT",

- "displayText": "RT",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+RT...",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+RT..."

- }

- },

- {

- "text": "Microsoft Surface Phone",

- "displayText": "Phone",

- "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+Phone",

- "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",

- "thumbnail": {

- "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+Phone..."

- }

- }],

- "pivotSuggestions": [...],

- "nextOffsetAddCount": 0

-}

-```

-The `queryExpansions` field contains a list of [Query](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#query_obj) objects. The `text` field contains the expanded query. The `displayText` field contains the expansion term. If the expanded query string is what the user is looking for, use the `text` and `thumbnail` fields to display the expanded query strings. Make the thumbnail and text clickable by using the `webSearchUrl` URL or the `searchLink` URL. Use `webSearchUrl` to send the user to the Bing search results. if you provide your own results page, use `searchLink`.

-<!-- Removing until we can replace with a sanitized image.

-The following shows an example Bing implementation that uses expanded queries. If the user clicks the Microsoft Surface Pro 3 link, they're taken to the Bing search results page, which shows them images of the Pro 3.

-

-## Throttling requests

-## Next steps

-If you haven't tried the Bing Image Search API before, try a [quickstart](../quickstarts/csharp.md). If you're looking for something more complex, try the tutorial to create a [single-page web app](../tutorial-bing-image-search-single-page-app.md).

-description: The Bing Image Search API enables you to also search across the entire Web for the most relevant .gif images.

-# Search for GIF images

-The Bing Image Search API enables you to also search across the entire Web for the most relevant .gif images.  Developers can integrate engaging gifs in various conversation scenarios. 

-The following URL is a query for animated .gif images.

-```

-https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=interesting&imageType=AnimatedGif&mkt=en-us

-```

-The [q](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#query) parameter specifies the search terms. The previous query also specifies `animatedGif` using the [imageType](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imagetype) filter parameter.

-To see examples of results, use the following URL to search bing.com.

-```

-https://www.bing.com/images/search?q=interesting&qft=%20filterui%3Aphoto-animatedgif

-```

-## Query parameters

-For more information about query parameters and options, see the [Image Search API reference](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#query-parameters). An example follows under the heading [Example search for animated gif using Java](#gifExample).

-## Tips and suggestions

-<a name="gifExample"></a>

-## Example search for animated gif using Java

-The following URL searches for animated .gif images: `q=interesting`

-```

-https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=interesting&imageType=AnimatedGif&mkt=en-us

-```

-As shown in the following example, the URL query requires [Ocp-Apim-Subscription-Key](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#headers) header.

-The following Java example builds and sends the request.

-```

-package gifSearch;

-import java.net.*;

-import java.util.*;

-import java.io.*;

-import javax.net.ssl.HttpsURLConnection;

-import com.google.gson.Gson;

-import com.google.gson.GsonBuilder;

-import com.google.gson.JsonObject;

-import com.google.gson.JsonParser;

-/*

- * Gson: https://github.com/google/gson

- * Maven info:

- * groupId: com.google.code.gson

- * artifactId: gson

- * version: 2.8.1

- *

- * Once you have compiled or downloaded gson-2.8.1.jar, assuming you have placed it in the

- * same folder as this file (BingImageSearch.java), you can compile and run this program at

- * the command line as follows.

- *

- * javac GIFsearch.java -classpath .;gson-2.8.1.jar -encoding UTF-8

- * java -cp .;gson-2.8.1.jar GIFsearch

- */

-public class GIFsearch {

- // Replace the subscriptionKey string value with your valid subscription key.

- static String subscriptionKey = "YOUR-ACCESS-KEY";

- static String host = "https://api.cognitive.microsoft.com";

- static String path = "/bing/v7.0/images/search";

- static String searchTerm = "interesting";

- public static SearchResults SearchImages (String searchQuery) throws Exception {

- // construct URL of search request (endpoint + query string)

- URL url = new URL(host + path + "?q=" + URLEncoder.encode(searchQuery, "UTF-8") + "&imageType=AnimatedGif&mkt=en-us");

- HttpsURLConnection connection = (HttpsURLConnection)url.openConnection();

- connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);

- // receive JSON body

- InputStream stream = connection.getInputStream();

- String response = new Scanner(stream).useDelimiter("\\A").next();

- // construct result object for return

- SearchResults results = new SearchResults(new HashMap<String, String>(), response);

- // extract Bing-related HTTP headers

- Map<String, List<String>> headers = connection.getHeaderFields();

- for (String header : headers.keySet()) {

- if (header == null) continue; // may have null key

- if (header.startsWith("BingAPIs-") || header.startsWith("X-MSEdge-")) {

- results.relevantHeaders.put(header, headers.get(header).get(0));

- }

- }

- stream.close();

- return results;

- }

- // pretty-printer for JSON; uses GSON parser to parse and re-serialize

- public static String prettify(String json_text) {

- JsonParser parser = new JsonParser();

- JsonObject json = parser.parse(json_text).getAsJsonObject();

- Gson gson = new GsonBuilder().setPrettyPrinting().create();

- return gson.toJson(json);

- }

- public static void main (String[] args) {

- if (subscriptionKey.length() != 32) {

- System.out.println("Invalid Bing Search API subscription key!");

- System.out.println("Please paste yours into the source code.");

- System.exit(1);

- }

- try {

- System.out.println("Searching the Web for: " + searchTerm);

- SearchResults result = SearchImages(searchTerm);

- System.out.println("\nRelevant HTTP Headers:\n");

- for (String header : result.relevantHeaders.keySet())

- System.out.println(header + ": " + result.relevantHeaders.get(header));

- System.out.println("\nJSON Response:\n");

- System.out.println(prettify(result.jsonResponse));

- }

- catch (Exception e) {

- e.printStackTrace(System.out);

- System.exit(1);

- }

- }

-}

-//Container class for search results encapsulates relevant headers and JSON data

-class SearchResults{

- HashMap<String, String> relevantHeaders;

- String jsonResponse;

- SearchResults(HashMap<String, String> headers, String json) {

- relevantHeaders = headers;

- jsonResponse = json;

- }

-}

-```

-## Results

-The code gets the following results as JSON objects:

-```json

- {

- "webSearchUrl": "https://www.bing.com/images/search?view\u003ddetai...",

- "name": "Very Interesting GIF - Thats Very Interesting - ...",

- "thumbnailUrl": "https://tse1.mm.bing.net/th?id\u003dOIP.yJX6Vz345JPK...",

- "datePublished": "2017-03-12T01:35:00.0000000Z",

- "contentUrl": "https://media.contoso.co/images/c895fa573df8e493ca8d0dec7d93b/raw",

- "hostPageUrl": "https://www.contoso.co/view/thats-very-interesting-christi...",

- "contentSize": "1295633 B",

- "encodingFormat": "animatedgif",

- "hostPageDisplayUrl": "https://www.contoso.co/view/thats-very-christian...",

- "width": 440,

- "height": 186,

- "thumbnail": {

- "width": 474,

- "height": 200

- },

- "imageInsightsToken": "ccid_yJX6Vz34*mid_9FF0FFA42AADA1357F042443D2103B40EA...",

- "insightsMetadata": {

- "recipeSourcesCount": 0,

- "bestRepresentativeQuery": {

- "text": "That\u0027s Very Interesting",

- "displayText": "That\u0027s Very Interesting",

- "webSearchUrl": "https://www.bing.com/images/search?q\u003dThat..."

- },

- "pagesIncludingCount": 19,

- "availableSizesCount": 2

- },

- "imageId": "9FF0FFA42AADA1357F042443D21030EAAA225F",

- "accentColor": "62452D"

- },

-```

-## Next steps

-description: Learn how to use the Bing Image Search API to get more information about an image.

-# Get image insights with the Bing Image Search API

-> [!IMPORTANT]

-> Instead of using the /images/details endpoint to get image insights, you should use [Visual Search](../bing-visual-search/overview.md) since it provides more comprehensive insights.

-Each image includes an insights token that you can use to get information about the image. For example, you can get a collection of related images, web pages that include the image, or a list of merchants where you can buy the product shown in the image.

-To get insights about an image, capture the image's [imageInsightsToken](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#image-imageinsightstoken) token in the response.

-```json

-"value" : [{

- . . .

- "name":"sailing dinghy.jpg",

- "imageInsightsToken" : "mid_D6426898706EC7..."

- "insightsSourcesSummary" : {

- "shoppingSourcesCount" : 9,

- "recipeSourcesCount" : 0

- },

- . . .

-}],

-```

-Next, call the Image Details endpoint and set the [insightsToken](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#insightstoken) query parameter to the token in `imageInsightsToken`.

-To specify the insights that you want to get, set the `modules` query parameter. To get all insights, set `modules` to `All`. To get only the caption and collection insights, set `modules` to `Caption%2CCollection`. For a complete list of possible insights, see [modules](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#modulesrequested). Not all insights are available for all images. The response includes all insights that you requested, if available.

-The following example requests all available insights for the preceding image.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/details?q=sailing+dinghy&insightsToken=mid_D6426898706EC7...&modules=All&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-## Getting insights of a known image

-If you have the URL to an image that you want to get insights of, use the [imgUrl](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imgurl) query parameter instead of the [insightsToken](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#insightstoken) parameter to specify the image. Or, if you have the image file, you may send the binary of the image in the body of a POST request. If you use a POST request, the `Content-Type` header must be set to `multipart/data-form`. With either option, the size of the image may not exceed 1 MB.

-If you have a URL to the image, the following example shows how to request insights of an image.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/details?q=sailing+dinghy&imgUrl=https%3A%2F%2Fwww.mydomain.com%2Fimages%2Fsunflower.png&modules=All&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-## Getting all image insights

-To request all insights of an image, set the [modules](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#modulesrequested) query parameter to `All`. To get related searches, the request must include the user's query string. This example shows using the [insightsToken](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#insightstoken) to specify the image.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/details?q=sailing+dinghy&insightsToken=mid_68364D764J...&modules=All&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-The top-level object is an [ImageInsightsResponse](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imageinsightsresponse) object instead of an [Images](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#images) object.

-```json

-{

- "_type" : "ImageInsights",

- "imageInsightsToken" : "bcid_3297E6A54E4787A5F51C49D9BA342B9A*ccid_Fe2Hx...",

- "bestRepresentativeQuery" : {

- "text" : "Sailing Dinghy",

- "displayText" : "Sailing Dinghy",

- "webSearchUrl" : "https:\/\/www.bing.com\/images\/search?q=Sailing+Dinghy...",

- },

- "pagesIncluding" : {

- "value" : [

- {

- "webSearchUrl" : "https:\/\/www.bing.com\/images\/search?view=...",

- "name" : "Powerboating Dublin, Dinghy Sailing Courses...",

- "thumbnailUrl" : "https:\/\/tse1.mm.bing.net\/th?id=OIP....",

- "datePublished" : "2017-01-20T00:41:00.0000000Z",

- "contentUrl" : "http:\/\/www.contoso.ie\/content...",

- "hostPageUrl" : "http:\/\/www.contoso.ie\/powerboating...",

- "contentSize" : "59063 B",

- "encodingFormat" : "jpeg",

- "hostPageDisplayUrl" : "www.contoso.ie\/powerboating...",

- "width" : 800,

- "height" : 600,

- "thumbnail" : {

- "width" : 300,

- "height" : 225

- },

- "imageInsightsToken" : "ccid_pHjQIA0x*mid_17F61B1316A39C92214...",

- "imageId" : "17F61B1316A39C922143FFDE9DFB5B0FB41171",

- "accentColor" : "0997C2"

- },

- . . .

- ]

- },

- "relatedSearches" : {

- "value" : [

- {

- "text" : "Sailing Fun",

- "displayText" : "Sailing Fun",

- "webSearchUrl" : "https:\/\/www.bing.com\/images\/search?q=Sailing...",

- "thumbnail" : {

- "url" : "https:\/\/tse1.mm.bing.net\/th?q=Sailing+Fun..."

- }

- },

- . . .

- ]

- },

- "visuallySimilarImages" : {

- "value" : [

- {

- "webSearchUrl" : "https:\/\/www.bing.com\/images\/search?view=...",

- "name" : "Weekend On the Water",

- "thumbnailUrl" : "https:\/\/tse2.mm.bing.net\/th?id=OIP...",

- "datePublished" : "2010-09-05T12:00:00.0000000Z",

- "contentUrl" : "http:\/\/1.bp.contoso.com\/_dc_6...",

- "hostPageUrl" : "http:\/\/contoso.com\/2010...",

- "contentSize" : "203806 B",

- "encodingFormat" : "jpeg",

- "hostPageDisplayUrl" : "contoso.com\/2010...",

- "width" : 1600,

- "height" : 1249,

- "thumbnail" : {

- "width" : 300,

- "height" : 234

- },

- "imageInsightsToken" : "ccid_Jg1Kwuc4*mid_5B7DA43976D3A422...",

- "imageId" : "5B7DA43976D3A422BA679A3AB019BB52C08DBC",

- "accentColor" : "0B2543"

- },

- . . .

- ]

- },

- "imageTags" : {

- "value" : [

- {

- "name" : "sail boat"

- },

- . . .

- ]

- }

-}

-```

-## Recognizing entities in an image

-The entity recognition feature identifies entities in an image, currently only people. To identify entities in an image, set the [modules](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#modulesrequested) query parameter to `RecognizedEntities`.

-> [!NOTE]

-> You may not specify this module with any other module. If you specify this module with other modules, the response does not include recognized entities.

-The following shows how to specify the image by using the [imgUrl](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#imgurl) parameter. Remember to URL encode the query parameters.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/details?q=faith+hill&insightsToken=mid_68364D764J...&modules=RecognizedEntities&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-The following shows the response to the previous request. Because the image contains two people, the response identifies a region for each person. In this case, the people were recognized in the CelebrityAnnotations and CelebRecognitionAnnotations groups. Bing lists the people in each group based on the likelihood that they match the person in the original image. The list is in descending order of confidence. The CelebRecognitionAnnotations group provides the highest level of confidence that the match is correct.

-```json

-{

- "_type" : "ImageInsights",

- "imageInsightsToken" : "ccid_ldi5nX38*mid_29470780DE0E6F969...",

- "recognizedEntityGroups" : {

- "value" : [

- {

- "recognizedEntityRegions" : [...],

- "name" : "CelebRecognitionAnnotations"

- },

- {

- "recognizedEntityRegions" : [...],

- "name" : "CelebrityAnnotations"

- }

- ]

- }

-}

-```

-The `region` field identifies the area of the image where Bing recognized the entity. For people, the region represents the person's face.

-The values of the rectangle are relative to the width and height of the original image and are in the range 0.0 through 1.0. For example, if the image is 300x200, and the region's top, left corner is at point (10, 20) and the bottom, right corner is at point (290, 150), then the normalized rectangle is:

-You can use the region that Bing returns in subsequent insights calls. For example, to get visually similar images of the recognized entity. For more information, see Cropping Images to use with Visually Similar and Entity Recognition Modules. The following shows the mapping between the region fields and the query parameters that you'd use to crop images.

-## Finding visually similar images

-To find images that are visually similar to the original image, set the [modules](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#modulesrequested) query parameter to SimilarImages.

-The following request shows how to get visually similar images. The request uses the [insightsToken](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#insightstoken) query parameter to identify the original image. To improve relevance, you should include the user's query string.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/details?insightsToken=mid_68364D764J...&modules=SimilarImages&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-The following shows the response to the previous request.

-```json

-{

- "_type" : "ImageInsights",

- "imageInsightsToken" : "ccid_ldi5nX38*mid_29470780DE0E6F969...",

- "visuallySimilarImages" : {

- "value" : [

- {

- "name" : "typical Hawaiian Sunset! :) | Scenes of Hawaii",

- "webSearchUrl" : "https:\/\/www.bing.com\/images\/search?view=detailv2...",

- "thumbnailUrl" : "https:\/\/tse1.mm.bing.net\/th?id=OIP.Mda2a86...",

- . . .

- }

- ]

- }

-```

-## Cropping images to use with visually similar and entity recognition modules

-To specify the region of the image that Bing uses to determine whether images are visually similar or to perform entity recognition, use the [cal](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#cal), [cat](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#cat), [cab](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#cab), and [car](/rest/api/cognitiveservices-bingsearch/bing-images-api-v7-reference#car) query parameters. By default, Bing uses the entire image.

-The parameters specify the top, left corner and bottom, right corner of the region that Bing uses for comparison. Specify the values as fractions of the original image's width and height. The fractional values start with (0.0, 0.0) at the top, left corner and end with (1.0, 1.0) at the bottom right corner. For example, to specify that the top, left corner starts a quarter of the way down from the top and a quarter of the way in from the left side, set `cal` to 0.25 and `cat` 0.25.

-The following sequence of calls shows the effect of specifying the cropping region. The first call does not include cropping and Bing recognizes two people standing side by side in the middle of the image.

-```

-GET https://api.cognitive.microsoft.com/bing/v7.0/images/details?modules=RecognizedEntities&imgurl=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.M0cbee6fadb43f35b2344e53da7a23ec1o0%26pid%3DApi&mkt=en-us HTTP/1.1

-Ocp-Apim-Subscription-Key: 123456789ABCDE

-User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

-X-MSEdge-ClientIP: 999.999.999.999

-X-Search-Location: lat:47.60357;long:-122.3295;re:100

-X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>

-Host: api.cognitive.microsoft.com

-```

-The response shows two recognized entities.

-```json

-{

- "_type" : "ImageInsights",

- "recognizedEntityGroups" : {

- "value": [

- . . .

- {

- "recognizedEntityRegions" : [{

- "region" : {