Azure文档智能服务：解决“密钥认证禁用”错误及替代方案

在使用Azure文档智能服务Python SDK时，遇到AuthenticationTypeDisabled错误通常表示Azure资源本身禁用了基于API密钥的认证方式。这不是代码逻辑错误，而是资源配置或组织安全策略所致。解决此问题需要检查Azure门户中的资源认证设置，或考虑采用更安全的Azure Active Directory (AAD) 认证方式，并在必要时联系Azure管理员获取相应权限。

azure文档智能服务（document intelligence，原名form recognizer）是一个强大的云服务，用于从文档中提取文本、键值对、表格和结构化数据。开发者通常通过其python sdk与服务进行交互，其中认证是连接到服务的第一步。

1. 问题描述：密钥认证失败

当尝试使用Azure文档智能服务的端点（endpoint）和API密钥（key）进行认证时，可能会遇到以下错误信息：

复制AI写代码

1 2 3

azure.core.exceptions.HttpResponseError: (AuthenticationTypeDisabled) Key based authentication is disabled for this resource. Code: AuthenticationTypeDisabled Message: Key based authentication is disabled for this resource.

此错误明确指出，当前资源已禁用基于API密钥的认证类型。这意味着即使提供的API密钥是正确的，服务也不会接受它，因为它根本没有启用这种认证机制。

以下是导致此错误的典型Python代码示例：

复制AI写代码

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

from azure.ai.formrecognizer import DocumentAnalysisClient from azure.core.credentials import AzureKeyCredential   # 请替换为您的实际端点和密钥 endpoint = "https://your-resource-name.cognitiveservices.azure.com/" key = "YOUR_API_KEY" # 此处应填入您的API密钥   def format_bounding_region(bounding_regions):     if not bounding_regions:         return "N/A"     return ", ".join("Page #{}: {}".format(region.page_number, format_polygon(region.polygon)) for region in bounding_regions)   def format_polygon(polygon):     if not polygon:         return "N/A"     return ", ".join(["[{}, {}]".format(p.x, p.y) for p in polygon])   def analyze_general_documents():     # 示例文档URL     docUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-layout.pdf"       # 初始化文档分析客户端     document_analysis_client = DocumentAnalysisClient(endpoint=endpoint, credential=AzureKeyCredential(key))       # 开始分析文档     poller = document_analysis_client.begin_analyze_document_from_url(             "prebuilt-document", docUrl)     result = poller.result()       # ... 后续处理结果的代码 ...     print("文档分析完成。")   if __name__ == "__main__":     analyze_general_documents()

2. 错误分析：AuthenticationTypeDisabled 的根本原因

AuthenticationTypeDisabled错误并非代码语法或逻辑问题。它直接来源于Azure文档智能服务资源的配置。在Azure中，资源可以配置多种认证方式，包括基于API密钥和基于Azure Active Directory (AAD) 的认证。当此错误发生时，通常意味着：

• 资源配置策略： 您的组织或订阅可能配置了严格的安全策略，默认禁用或强制禁用API密钥认证，以强制使用更安全的AAD认证。
• 手动禁用： 资源管理员可能在Azure门户中手动禁用了API密钥认证。
• 权限不足： 作为用户，您可能没有足够的权限来修改资源的认证设置，或者无法使用当前环境中配置的密钥。

值得注意的是，代码中 DocumentAnalysisClient(endpoint=endpoint, credential=AzureKeyCredential(key)) 的写法在API密钥认证启用时是完全正确的。

3. 解决方案与建议

解决此问题主要有以下几个方向：

3.1 验证并修改Azure资源配置（如果允许）

如果您的权限允许，或者您可以联系到Azure管理员，请按照以下步骤检查并修改文档智能服务资源的认证设置：

1. 登录Azure门户： 访问 portal.azure.com。
2. 导航到文档智能服务资源： 在搜索栏中输入您的文档智能服务资源名称，并导航到该资源的概览页面。
3. 检查认证设置： 在资源菜单中查找与“身份验证”、“密钥”或“网络”相关的设置。不同的Azure服务和版本可能位置略有不同。通常，您会在“资源管理”或“安全”部分找到管理API密钥的选项，以及可能存在的认证类型开关。
4. 启用密钥认证： 如果发现密钥认证被禁用，并且您的组织策略允许，请尝试启用它。
5. 重新生成密钥： 确保您使用的密钥是最新且有效的。

重要提示： 在企业环境中，强烈建议遵循组织的安全策略。如果策略要求禁用API密钥认证，请不要随意启用。

3.2 采用Azure Active Directory (AAD) 认证（推荐）

Azure Active Directory (AAD) 认证是更安全、更灵活的认证方式，特别适用于企业级应用。当API密钥认证被禁用时，使用AAD认证是最佳实践。

要使用AAD认证，您需要安装 azure-identity 库，并使用 DefaultAzureCredential。DefaultAzureCredential 会尝试通过多种方式（如环境变量、托管标识、Azure CLI、Visual Studio Code等）获取凭据。

步骤：

1. 安装必要的库：

   复制AI写代码

   1	pip install azure-identity

2. 修改Python代码：将 AzureKeyCredential 替换为 DefaultAzureCredential。

   复制AI写代码

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

   from azure.ai.formrecognizer import DocumentAnalysisClient from azure.core.credentials import AzureKeyCredential # 仍然可以保留，但不再用于初始化 from azure.identity import DefaultAzureCredential # 导入DefaultAzureCredential   endpoint = "https://your-resource-name.cognitiveservices.azure.com/" # key = "YOUR_API_KEY" # 不再直接使用API密钥   def format_bounding_region(bounding_regions):     # ... (与之前相同) ...     if not bounding_regions:         return "N/A"     return ", ".join("Page #{}: {}".format(region.page_number, format_polygon(region.polygon)) for region in bounding_regions)   def format_polygon(polygon):     # ... (与之前相同) ...     if not polygon:         return "N/A"     return ", ".join(["[{}, {}]".format(p.x, p.y) for p in polygon])   def analyze_general_documents():     docUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-layout.pdf"       # 使用DefaultAzureCredential进行认证     credential = DefaultAzureCredential()     document_analysis_client = DocumentAnalysisClient(endpoint=endpoint, credential=credential)       poller = document_analysis_client.begin_analyze_document_from_url(             "prebuilt-document", docUrl)     result = poller.result()       # ... 后续处理结果的代码 ...     print("文档分析完成。")   if __name__ == "__main__":     analyze_general_documents()

3. 配置本地环境以使用AAD认证：

   • Azure CLI： 在终端运行 az login 进行登录。DefaultAzureCredential 会自动检测并使用您的CLI凭据。
   • 环境变量： 设置 AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET (适用于服务主体) 或 AZURE_USERNAME, AZURE_PASSWORD (不推荐用于生产环境)。
   • 托管标识： 如果您的代码运行在Azure虚拟机、Azure应用服务等支持托管标识的环境中，DefaultAzureCredential 会自动利用这些标识。

3.3 联系Azure管理员

如果您不确定如何配置Azure资源，或者没有权限进行更改，最直接有效的方法是联系您的Azure管理员或IT团队。他们可以帮助您：

• 确认资源认证策略。
• 授予您必要的权限。
• 指导您如何使用正确的认证方法（例如，提供服务主体的凭据）。

4. 总结与注意事项

• 错误性质： AuthenticationTypeDisabled 是一个资源配置错误，而非代码语法错误。您提供的Python代码在API密钥认证启用时是正确的。
• 安全性考量： 许多组织出于安全考虑会禁用API密钥认证，并倾向于使用AAD认证。AAD提供了更精细的访问控制、更好的审计能力和更安全的凭据管理。
• 调试思路： 当遇到此类认证错误时，首先应检查Azure门户中的资源配置，其次考虑切换到推荐的AAD认证方式。

通过理解此错误的原因并采取相应的解决策略，您可以有效地连接到Azure文档智能服务并利用其强大的功能。