解决Azure文档智能服务“密钥认证被禁用”错误：综合指南

Azure文档智能服务认证错误解析

在使用Azure文档智能服务（Document Intelligence）进行文档内容提取时，开发者通常会通过服务终结点（endpoint）和访问密钥（key）进行身份验证。然而，有时即使代码逻辑正确，也可能遇到 HttpResponseError: (AuthenticationTypeDisabled) Key based authentication is disabled for this resource. 这样的错误。这个错误明确指出，当前Azure资源已禁用基于密钥的身份验证方式。

错误现象与代码示例

以下是一个典型的Python代码片段，用于连接Azure文档智能服务并分析文档。当遇到上述认证错误时，代码在尝试创建 DocumentAnalysisClient 并发起分析请求时会失败。

当上述代码执行时，如果Azure资源禁用了密钥认证，将会在 document_analysis_client.begin_analyze_document_from_url 调用时抛出 HttpResponseError。

根本原因：Azure资源配置

此错误的根本原因在于Azure文档智能服务实例的身份验证设置。Azure提供了多种身份验证方式，包括：

1. 基于密钥的身份验证 (Key-based authentication)：这是最常见的，通过终结点和API密钥进行认证。
2. Azure Active Directory (AAD) 身份验证：通过Azure AD进行身份验证，提供更细粒度的访问控制和企业级安全功能。

为了增强安全性或遵循组织策略，Azure管理员可能会选择禁用基于密钥的身份验证，强制所有访问都通过Azure AD进行。一旦禁用，即使提供了正确的API密钥，服务也会拒绝连接。

解决方案与注意事项

解决此问题需要从Azure资源配置层面入手，而不是修改代码逻辑。

1. 检查Azure资源身份验证设置：

   

   ai-github-radar

   跟踪分析高增长或重大更新的AI原生工具与GitHub仓库，揭示AI工作流与生态的新兴趋势。

   下载
   • 登录Azure门户。
   • 导航到您的文档智能服务（Document Intelligence）资源。
   • 在资源菜单中，查找与“身份验证”、“访问控制”或“密钥和终结点”相关的设置。
   • 确认“密钥认证”是否被禁用。如果被禁用，您需要联系Azure管理员以启用它，或者切换到Azure AD身份验证。

2. 联系Azure管理员：

   • 如果您的组织有严格的安全策略，可能会默认禁用密钥认证。在这种情况下，您需要联系负责管理Azure资源的管理员。
   • 管理员可以：
     • 为您的资源重新启用密钥认证（如果允许）。
     • 为您提供使用Azure AD进行身份验证所需的权限和指导。
     • 提供一个已启用密钥认证的新资源，或者一个您有权访问的现有资源。

3. 考虑使用Azure AD身份验证（推荐）：

   • 如果密钥认证被禁用是出于安全考虑，那么切换到Azure AD身份验证是更专业的做法。

   • 使用Azure AD，您可以利用服务主体（Service Principal）或托管标识（Managed Identity）进行身份验证，这通常比直接使用API密钥更安全、更易于管理。

   • 示例 (使用Azure AD默认凭据，适用于Azure环境或配置了Azure CLI/环境变量的情况):

     复制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

     from azure.ai.formrecognizer import DocumentAnalysisClient from azure.identity import DefaultAzureCredential # 导入DefaultAzureCredential   endpoint = "https://your-resource-name.cognitiveservices.azure.com/"   def analyze_with_aad():     docUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-layout.pdf"       # 使用DefaultAzureCredential进行身份验证     # 它会尝试通过多种方式（环境变量、Managed Identity、Azure CLI等）获取凭据     credential = DefaultAzureCredential()     document_analysis_client = DocumentAnalysisClient(endpoint=endpoint, credential=credential)       print("尝试使用Azure AD凭据连接Azure文档智能服务并分析文档...")     try:         poller = document_analysis_client.begin_analyze_document_from_url("prebuilt-document", docUrl)         result = poller.result()         print("文档分析成功（使用AAD认证）！")         # ... 打印结果 ...     except Exception as e:         print(f"文档分析失败（使用AAD认证）: {e}")   if __name__ == "__main__":     analyze_with_aad()

   • 要使 DefaultAzureCredential 工作，您需要确保运行代码的环境已正确配置了Azure AD凭据，例如通过 az login 登录Azure CLI，或者配置了相应的环境变量。

总结

当您遇到Azure文档智能服务 AuthenticationTypeDisabled 错误时，请记住问题不在于您的Python代码逻辑，而在于Azure资源的身份验证配置。务必检查您的Azure资源设置，并在必要时与您的Azure管理员协作，以启用密钥认证或切换到更安全的Azure AD身份验证方式。理解并正确配置Azure资源的身份验证机制是成功集成云服务的关键一步。