Custom subdomain names for Cognitive Services

• 12/04/2020
• 2 minutes to read
• • e
  • a
  • D
  • n
  • t

Azure Cognitive Services use custom subdomain names for each resource created through the Azure portal, Azure Cloud Shell, or Azure CLI. Unlike regional endpoints, which were common for all customers in a specific Azure region, custom subdomain names are unique to the resource. Custom subdomain names are required to enable features like Azure Active Directory (Azure AD) for authentication.

How does this impact existing resources?

Cognitive Services resources created before July 1, 2019 will use the regional endpoints for the associated service. These endpoints will work with existing and new resources.

If you'd like to migrate an existing resource to leverage custom subdomain names, so that you can enable features like Azure AD, follow these instructions:

1. Sign in to the Azure portal and locate the Cognitive Services resource that you'd like to add a custom subdomain name to.
2. In the Overview blade, locate and select Generate Custom Domain Name.
3. This opens a panel with instructions to create a unique custom subdomain for your resource.

   Warning

   After you've created a custom subdomain name it cannot be changed.

Do I need to update my existing resources?

No. The regional endpoint will continue to work for new and existing Cognitive Services and the custom subdomain name is optional. Even if a custom subdomain name is added the regional endpoint will continue to work with the resource.

What if an SDK asks me for the region for a resource?

Regional endpoints and custom subdomain names are both supported and can be used interchangeably. However, the full endpoint is required.

Region information is available in the Overview blade for your resource in the Azure portal. For the full list of regional endpoints, see Is there a list of regional endpoints?

Are custom subdomain names regional?

Yes. Using a custom subdomain name doesn't change any of the regional aspects of your Cognitive Services resource.

What are the requirements for a custom subdomain name?

A custom subdomain name is unique to your resource. The name can only include alphanumeric characters and the - character; it must be between 2 and 64 characters in length and cannot end with a -.

Can I change a custom domain name?

No. After a custom subdomain name is created and associated with a resource it cannot be changed.

Can I reuse a custom domain name?

Each custom subdomain name is unique, so in order to reuse a custom subdomain name that you've assigned to a Cognitive Services resource, you'll need to delete the existing resource. After the resource has been deleted, you can reuse the custom subdomain name.

Is there a list of regional endpoints?

Yes. This is a list of regional endpoints that you can use with Azure Cognitive Services resources.

See also

• What are the Cognitive Services?
• Authentication