使用AWS Textract QUERIES功能遇错，调用API返回UnknownOperationException

问题现象 #

• 使用boto3调用AWS Textract的QUERIES功能时，系统提示“queries config不是有效参数”
• 改用手动签名调用API时，返回<UnknownOperationException/>错误

提供的代码 #

import requests
import boto3
import sys, os, base64, datetime, hashlib, hmac 
import json

session = boto3.Session()
credentials = session.get_credentials()
credentials = credentials.get_frozen_credentials()
access_key = credentials.access_key
secret_key = credentials.secret_key
print()
method = 'POST'
service = 'textract'
amz_target   = 'Textract.StartDocumentAnalysis'
host = 'textract.us-east-1.amazonaws.com'
region = 'us-east-1'
endpoint = 'https://textract.us-east-1.amazonaws.com'
canonical_uri = '/'
content_type = 'application/x-amz-json-1.1'
# request_parameters = 'Action=DescribeRegions&Version=2013-10-15'
def sign(key, msg):
    return hmac.new(key, msg.encode('utf-8'), hashlib.sha256).digest()

def getSignatureKey(key, dateStamp, regionName, serviceName):
    kDate = sign(('AWS4' + key).encode('utf-8'), dateStamp)
    kRegion = sign(kDate, regionName)
    kService = sign(kRegion, serviceName)
    kSigning = sign(kService, 'aws4_request')
    return kSigning

# Create a date for headers and the credential string
t = datetime.datetime.utcnow()
amz_date = t.strftime('%Y%m%dT%H%M%SZ')
date_stamp = t.strftime('%Y%m%d') # Date w/o time, used in credential scope
amz_target = 'Textract.'
canonical_headers = 'content-type:' + content_type + '\n' + 'host:' + host + '\n' + 'x-amz-date:' + amz_date + '\n' + 'x-amz-target:' + amz_target + '\n'

signed_headers = 'content-type;host;x-amz-date;x-amz-target'
canonical_querystring = ''
payload = {
    
   "DocumentLocation": { 
      "S3Object": { 
         "Bucket": "",
         "Name": "",
      }
   },
   "FeatureTypes": [ "FORMS" ],
   "JobTag": "123",
   "NotificationChannel": { 
      "RoleArn": "",
      "SNSTopicArn": ""
   },
    "QueriesConfig": { 
       "Queries": [ 
          { 
             "Alias": "string",
             "Pages": [ "1-4" ],
             "Text": "what is the policy number ?"
         }
      ]
   }
}
payload_hash = hashlib.sha256(json.dumps(payload).encode('utf-8')).hexdigest()

canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash

algorithm = 'AWS4-HMAC-SHA256'
credential_scope = date_stamp + '/' + region + '/' + service + '/' + 'aws4_request'
string_to_sign = algorithm + '\n' +  amz_date + '\n' +  credential_scope + '\n' +  hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()

signing_key = getSignatureKey(secret_key, date_stamp, region, service)

signature = hmac.new(signing_key, (string_to_sign).encode('utf-8'), hashlib.sha256).hexdigest()

authorization_header = algorithm + ' ' + 'Credential=' + access_key + '/' + credential_scope + ', ' +  'SignedHeaders=' + signed_headers + ', ' + 'Signature=' + signature

headers = {'Content-Type':content_type,
           'X-Amz-Date':amz_date,
           'X-Amz-Target':amz_target,
           'Authorization':authorization_header}
print('Request URL = ' + endpoint)


r = requests.post("https://textract.us-east-1.amazonaws.com", data=json.dumps(payload), headers=headers)

print(r.text)

错误原因分析 #

1. boto3版本过低：Textract的QUERIES功能属于较新特性，旧版boto3未支持QueriesConfig参数，导致报错。
2. 手动API调用的致命错误：代码中错误地将amz_target覆盖为'Textract.'，正确值应为'Textract.StartDocumentAnalysis'，这直接触发了<UnknownOperationException/>。
3. Payload配置错误：
   • FeatureTypes未包含QUERIES，这是启用查询功能的必要条件
   • Alias字段非必填，且S3存储桶、文档名称、角色ARN、SNS主题ARN均未填写实际有效值

修复方案 #

方案1：升级boto3并使用官方SDK调用（推荐）

这是最简洁可靠的方式，避免手动签名的复杂问题：

import boto3

# 初始化Textract客户端
textract = boto3.client('textract', region_name='us-east-1')

# 调用StartDocumentAnalysis，启用QUERIES功能
response = textract.start_document_analysis(
    DocumentLocation={
        'S3Object': {
            'Bucket': '你的存储桶名称',
            'Name': '你的文档名称'
        }
    },
    FeatureTypes=['QUERIES'],  # 必须指定QUERIES
    QueriesConfig={
        'Queries': [
            {
                'Text': 'what is the policy number ?',
                'Pages': ['1-4']
            }
        ]
    },
    JobTag='123',
    NotificationChannel={
        'RoleArn': '你的IAM角色ARN',
        'SNSTopicArn': '你的SNS主题ARN'
    }
)

print(response)

注意：

• 执行pip install --upgrade boto3升级到≥1.26.0版本
• 确保IAM角色拥有Textract调用权限和SNS发布权限

方案2：修复手动签名的API调用代码

针对你提供的代码，需修改以下几点：

1. 删除错误的amz_target = 'Textract.'赋值，保留初始的amz_target = 'Textract.StartDocumentAnalysis'
2. 将FeatureTypes改为["QUERIES"]（或同时包含FORMS和QUERIES）
3. 填写DocumentLocation和NotificationChannel中的实际有效值
4. 可选：移除Queries中的Alias字段（非必填）

修复后的关键代码片段：

# 保留正确的目标操作
amz_target = 'Textract.StartDocumentAnalysis'

# 修正后的Payload
payload = {
    "DocumentLocation": { 
        "S3Object": { 
            "Bucket": "你的存储桶名称",
            "Name": "你的文档名称"
        }
    },
    "FeatureTypes": [ "QUERIES" ],  # 必须包含QUERIES
    "JobTag": "123",
    "NotificationChannel": { 
        "RoleArn": "你的IAM角色ARN",
        "SNSTopicArn": "你的SNS主题ARN"
    },
    "QueriesConfig": { 
        "Queries": [ 
            { 
                "Pages": [ "1-4" ],
                "Text": "what is the policy number ?"
            }
        ]
    }
}

内容的提问来源于stack exchange，提问作者Javier Perez