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

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

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

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

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代码示例：

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密钥认证，请不要随意启用。

JoinMC智能客服

JoinMC智能客服，帮您熬夜加班，7X24小时全天候智能回复用户消息，自动维护媒体主页，全平台渠道集成管理，电商物流平台一键绑定，让您出海轻松无忧！

23

查看详情

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

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

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

步骤：

1. 安装必要的库：

   pip install azure-identity

   登录后复制

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

   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文档智能服务并利用其强大的功能。

以上就是Azure文档智能服务：解决“密钥认证禁用”错误及替代方案的详细内容，更多请关注php中文网其它相关文章！