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管理员，请按照以下步骤检查并修改文档智能服务资源的认证设置：
- 登录Azure门户： 访问 portal.azure.com。
- 导航到文档智能服务资源： 在搜索栏中输入您的文档智能服务资源名称，并导航到该资源的概览页面。
- 检查认证设置： 在资源菜单中查找与“身份验证”、“密钥”或“网络”相关的设置。不同的Azure服务和版本可能位置略有不同。通常，您会在“资源管理”或“安全”部分找到管理API密钥的选项，以及可能存在的认证类型开关。
- 启用密钥认证： 如果发现密钥认证被禁用，并且您的组织策略允许，请尝试启用它。
- 重新生成密钥： 确保您使用的密钥是最新且有效的。
重要提示： 在企业环境中，强烈建议遵循组织的安全策略。如果策略要求禁用API密钥认证，请不要随意启用。
3.2 采用Azure Active Directory (AAD) 认证（推荐）
Azure Active Directory (AAD) 认证是更安全、更灵活的认证方式，特别适用于企业级应用。当API密钥认证被禁用时，使用AAD认证是最佳实践。
要使用AAD认证，您需要安装 azure-identity 库，并使用 DefaultAzureCredential。DefaultAzureCredential 会尝试通过多种方式（如环境变量、托管标识、Azure CLI、Visual Studio Code等）获取凭据。
步骤：
-
安装必要的库：
pip install azure-identity
-
修改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() -
配置本地环境以使用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文档智能服务并利用其强大的功能。
