足球API网关目标

适用于AWS Bedrock AgentCore网关的RapidAPI Football API集成。将足球数据访问部署到任何网关，作为MCP兼容目标。

概述

该项目将RapidAPI Football API部署为AWS Bedrock AgentCore Gateway的OpenAPI目标，使人工智能代理能够查询：

欧洲前5名联赛赛程、结果和排名
欧洲冠军联赛和欧洲联赛数据
球员统计数据（得分王、助攻数）
国内杯赛

主要特点

✨ 全自动部署：自定义资源自动配置网关服务角色权限
多网关支持：通过简单的环境配置部署到多个网关
内置联赛ID：在工具描述中预先配置的常见联盟，将API调用减少50%
共享凭据：一个RapidAPI密钥可用于多个网关部署
CDK资产管理：OpenAPI模式自动上传到CDK暂存桶
安全凭据：存储在AWS Secrets Manager中的RapidAPI密钥
幂等：多次部署安全，智能权限合并

先决条件

Node.js：>=18.x
AWS-CLI：已配置凭据
AWS CDK: >= 2.100.0
无效账户：主动订阅足球API
现有网关：目标网关必须存在于您的AWS帐户中

创建AgentCore网关

如果您没有现有的网关，则需要先创建一个。网关是代理通过模型上下文协议（MCP）访问工具和资源的统一入口点。

快速启动选项

选择以下方法之一创建网关：

方法	最适合	命令示例
AWS控制台	可视化界面，首次设置	带分步向导的Web UI
AWS-CLI	简单自动化，IAM身份验证	`aws bedrock-agentcore-control create-gateway --name my-gateway --authorizer-type AWS_IAM ...`
AgentCore工具包	自动OAuth设置	`agentcore create_mcp_gateway --region us-west-2 --name my-gateway`

AWS CLI示例（IAM授权-最简单）

aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::123456789012:role/MyAgentCoreServiceRole \
  --protocol-type MCP \
  --authorizer-type AWS_IAM \
  --region us-west-2

网关创建后

从输出中保存这些值：

gatewayIdentifier → 在中使用 .env 文件为 GATEWAY_IDENTIFIER
gatewayUrl → 用于连接客户端的MCP端点URL
roleArn → 网关服务角色ARN

重要说明

语义搜索：只能在网关创建期间启用（以后不能更改）
IAM权限：此CDK堆栈通过自定义资源自动添加凭据提供程序权限
服务角色：您只需要基本的网关权限；凭证提供者访问权限是自动添加的

📚 完整的文件:

快速开始

1.安装依赖项

npm install

2.配置环境

复制 .env.example 到特定于网关的env文件：

cp .env.example .env.my-gateway.local
# Edit and set:
# - GATEWAY_IDENTIFIER: Your gateway identifier
# - CREDENTIAL_PROVIDER_NAME: Your credential provider name

3.一次性设置：创建凭据提供程序

步骤1：创建凭据提供程序

# Create credential provider (only once for shared strategy)
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name FootballAPICredentialProvider \
  --description "RapidAPI Football API Key (shared)" \
  --profile default --region

步骤2：存储您的RapidAPI密钥

从以下位置获取RapidAPI密钥：https://rapidapi.com/api-sports/api/api-football

然后使用您的API密钥更新凭据提供商：

# IMPORTANT: Use bedrock-agentcore-control to update the API key
# DO NOT use secretsmanager put-secret-value directly
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name FootballAPICredentialProvider \
  --api-key "YOUR_RAPID_API_KEY" \
  --profile default --region

为什么要使用更新api密钥凭据提供程序？

这个秘密由 bedrock-agentcore-identity 服务
Direct Secrets Manager操作可能会因服务所有权而失败
此命令可确保格式正确({"apiKey": "..."})自动
为无效密钥提供更好的错误消息

常见问题：

❌ 错误： {"api_key": "..."} 或 {"api_key_value": "..."}
✅ 对的： {"apiKey": "..."} （由命令自动处理）
如果API调用返回“错误/缺少应用程序密钥”，请验证密钥是否已成功更新

4.Bootstrap CDK（仅限首次使用）

cdk bootstrap --profile default

5.部署到网关

./deploy.sh .env.my-gateway.local

建筑

┌─────────────────────────────────────────────────────┐
│ AWS Bedrock AgentCore Gateway (pre-existing)        │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │ GatewayRoleUpdater (Custom Resource)       │    │
│  │  ↓ Automatically adds IAM permissions      │    │
│  │  ↓ to Gateway service role                 │    │
│  └────────────────────────────────────────────┘    │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │ FootballAPITarget (OpenAPI Target)         │    │
│  │                                             │    │
│  │  • OpenAPI Schema (CDK Asset → S3)         │    │
│  │  • API Key (Secrets Manager)               │    │
│  │  • Credential Provider: API_KEY            │    │
│  │  • Headers: x-rapidapi-key, x-rapidapi-host│    │
│  └────────────────────────────────────────────┘    │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │ Available Tools:                            │    │
│  │  • getFixtures                              │    │
│  │  • getStandings                             │    │
│  │  • getTopScorers                            │    │
│  │  • getTopAssists                            │    │
│  │  • getLeagues (fallback)                    │    │
│  └────────────────────────────────────────────┘    │
└──────────────────┬───────────────────────────────────┘
                   │ RapidAPI Key from Secrets Manager
                   ▼
            RapidAPI Football API v3
          (https://v3.football.api-sports.io)

部署流程

cdk deploy
  ↓
1. GatewayRoleUpdater (Custom Resource)
   ├── Lambda checks Gateway service role
   ├── Adds missing IAM permissions
   └── ✅ Role updated automatically
  ↓
2. OpenAPI Schema Asset
   └── Upload to S3
  ↓
3. Gateway Target
   ├── Reference Gateway
   ├── Reference Credential Provider
   └── Link OpenAPI schema from S3
  ↓
✅ Target READY (fully automated)

可用工具

1.装配夹具

获取比赛赛程、结果和时间表。

参数：

league （整数）：联赛ID（见下面的常用ID）
season （整数，必填）：季节年份（例如2024/2025年为2024年）
date （字符串）：匹配日期（YYYY-MM-DD）
last （整数）：获取最后N个匹配项
next （整数）：获取接下来的N场比赛
status （字符串）：比赛状态（FT=全职，LIVE=进行中，NS=未开始）
team （整数）：按团队ID筛选

示例：

// Premier League last 10 matches
{ league: 39, season: 2024, last: 10 }

// Champions League next 5 matches
{ league: 2, season: 2024, next: 5 }

// La Liga matches on specific date
{ league: 140, season: 2024, date: "2024-11-10" }

// Live matches across all leagues
{ season: 2024, status: "LIVE" }

2.获得展位

获取联赛排名/表格。

参数：

league （整数，必填）：联赛ID
season （整数，必填）：季节年份
team （整数）：特定团队ID

示例：

// Premier League standings
{ league: 39, season: 2024 }

// Serie A standings
{ league: 135, season: 2024 }

3.获得高分

获得最高分。

参数：

league （整数，必填）：联赛ID
season （整数，必填）：季节年份

示例：

// Bundesliga top scorers
{ league: 78, season: 2024 }

4.获取TopAssists

获得顶级助攻领袖。

参数：

league （整数，必填）：联赛ID
season （整数，必填）：季节年份

5.获取联赛

搜索联赛（仅用于不常见的联赛）。

参数：

id （整数）：特定联赛ID
name （string）：按名称搜索
country （string）：按国家筛选
season （整数）：按季节筛选
current （布尔值）：仅限活动联赛

普通联赛ID

欧洲五大联赛

英超联赛 （英国）： 39
西甲联赛 （西班牙）： 140
意甲联赛 （意大利）： 135
德甲（德国）： 78
联赛 1 （法国）： 61

欧洲竞赛

欧洲冠军联赛: 2
欧洲足球联赛: 3

国内杯

足总杯 （英国）： 45
国王杯 （西班牙）： 143
意大利杯 （意大利）： 137
德国杯 （德国）： 81
法国杯 （法国）： 66

优化策略

OpenAPI模式在工具描述中包含了常见的联盟ID，从而实现了：

直接使用：AI代理可以立即使用普通联赛的联赛ID
减少了API调用：无需查询 getLeagues 用于流行比赛
更快的响应：消除了一个API往返行程（节省200-500ms）
配额节省：将API在典型查询中的使用量减少约50%

示例流程（优化）：

User: "Get Premier League standings"
→ Agent directly calls: getStandings({ league: 39, season: 2024 })
→ API calls: 1

示例流程（未优化）：

User: "Get Premier League standings"
→ Agent calls: getLeagues({ name: "Premier League" })
→ Agent calls: getStandings({ league: 39, season: 2024 })
→ API calls: 2 ❌

季节参数指南

API足球使用年份来表示赛季：

2024 = 2024/2025赛季 （2024年8月至2025年5月）
2023 = 2023/2024赛季 （2023年8月至2024年5月）
2022 = 2022/2023赛季 （2022年8月至2023年5月）

例子： 对于2024年11月的比赛，请使用 season: 2024 （当前2024/2025赛季）。

快速使用示例

查看英超联赛排名

Tool: getStandings
Parameters: { "league": 39, "season": 2024 }

获取今天的冠军联赛比赛

Tool: getFixtures
Parameters: { "league": 2, "season": 2024, "date": "2024-11-10" }

比较前5名联赛的顶级得分者

# AI agent can call these in parallel:
getTopScorers({ "league": 39, "season": 2024 })   # Premier League
getTopScorers({ "league": 140, "season": 2024 })  # La Liga
getTopScorers({ "league": 135, "season": 2024 })  # Serie A
getTopScorers({ "league": 78, "season": 2024 })   # Bundesliga
getTopScorers({ "league": 61, "season": 2024 })   # Ligue 1

常见错误

超出费率限制

{ "errors": { "requests": "The request limit has been reached" } }

解决方案： 升级RapidAPI计划或等待配额重置。

联盟ID无效

{ "errors": { "league": "Invalid league id" } }

解决方案： 使用 getLeagues 以搜索正确的联盟ID。

未返回数据

{ "results": 0, "response": [] }

原因： 赛季不正确、联赛不活跃或日期超出范围。

RapidAPI速率限制

免费计划：100个请求/天
基础方案：500个请求/天（10美元/月）
专业计划：5 000次请求/天（35美元/月）

在RapidAPI仪表板中监控使用情况：https://rapidapi.com/developer/dashboard

项目结构

agentcore-gateway-targets/
├── schemas/
│   └── football-api-openapi.yaml       # OpenAPI 3.0 schema with embedded league IDs
├── lib/
│   └── football-gateway-stack.ts        # CDK Stack implementation
├── bin/
│   └── football-gateway-app.ts          # CDK App entry point
├── deploy.sh                            # Deployment script for CDK stack
├── package.json                         # Node.js dependencies
├── tsconfig.json                        # TypeScript configuration
├── cdk.json                             # CDK configuration
├── .env.example                         # Environment template
├── .env.*.local                         # Gateway-specific configs (git-ignored)
├── CLAUDE.md                            # Project documentation (environment-agnostic)
├── CLAUDE.local.md                      # Environment-specific notes (git-ignored)
└── README.md                            # This file

发展

构建

npm run build

观看模式

npm run watch

CDK命令

# List stacks
cdk list

# Show diff
cdk diff

# Synthesize CloudFormation
cdk synth

# Deploy
cdk deploy --profile default

# Destroy (remove target)
cdk destroy --profile default

验证

部署后，验证目标：

# List all targets on your gateway
aws bedrock-agentcore-control list-gateway-targets \
  --gateway-identifier  \
  --profile default --region 

# Get specific target details
aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier  \
  --target-id  \
  --profile default --region

故障排除

目标创建失败

检查网关是否存在： aws bedrock-agentcore-control get-gateway --gateway-identifier
验证凭据提供程序是否存在以及名称是否正确
检查CloudWatch日志是否有错误
验证OpenAPI模式语法

API调用失败

验证RapidAPI订阅是否处于活动状态
在机密管理器中检查API密钥
确保x-rapidapi-host头球匹配
查看速率限制状态

架构验证错误

确保所有操作 operationId
避免一个/任何/所有构造
使用简单的参数结构
使用OpenAPI验证器进行验证：https://validator.swagger.io/

成本考虑

AWS成本

AgentCore网关：按工具调用付费
拉姆达 （GatewayRoleUpdater）：每次部署约0.01美元（适用于免费层）
CloudWatch日志：可忽略不计（保留7天）
秘密经理：每个秘密约0.40美元/月
S3存储：可忽略不计（架构文件\<1KB）
云层形成：免费

Agentcore Football API

快速接入

详细介绍

足球API网关目标

概述

主要特点

先决条件

创建AgentCore网关

快速启动选项

AWS CLI示例（IAM授权-最简单）

网关创建后

重要说明

快速开始

1.安装依赖项

2.配置环境

3.一次性设置：创建凭据提供程序

4.Bootstrap CDK（仅限首次使用）

5.部署到网关

建筑

部署流程

可用工具

1.装配夹具

2.获得展位

3.获得高分

4.获取TopAssists

5.获取联赛

普通联赛ID

欧洲五大联赛

欧洲竞赛

国内杯

优化策略

季节参数指南

快速使用示例

查看英超联赛排名

获取今天的冠军联赛比赛

比较前5名联赛的顶级得分者

常见错误

超出费率限制

联盟ID无效

未返回数据

RapidAPI速率限制

项目结构

发展

构建

观看模式

CDK命令

验证

故障排除

目标创建失败

API调用失败

架构验证错误

成本考虑

AWS成本

RapidAPI成本

参考文献

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP