如何在GitHub README中添加Kaggle数据集下载统计徽章？

核心思路 #

因为没有现成的第三方徽章服务支持Kaggle下载量展示，所以可以通过GitHub Actions定时拉取数据+自定义动态徽章的方式实现实时更新效果。

具体步骤 #

1. 配置Kaggle API权限

   • 登录Kaggle账户，在「Account」页面生成并下载kaggle.json API令牌文件。
   • 打开GitHub目标仓库的「Settings → Secrets and variables → Actions」，添加两个秘密变量：
     • KAGGLE_USERNAME：你的Kaggle用户名
     • KAGGLE_KEY：kaggle.json里的密钥字段

2. 编写Python脚本获取下载量
   在仓库根目录创建update_downloads.py脚本，替换成你的数据集信息：

   import kaggle
   import json
   
   # 初始化Kaggle API
   kaggle.api.authenticate()
   
   # 替换为你的数据集标识（格式：用户名/数据集名称）
   dataset_slug = "your-username/your-dataset-name"
   dataset_info = kaggle.api.dataset_list_files(dataset_slug, quiet=True)[0].dataset
   
   # 获取最新下载量并生成徽章配置
   download_count = dataset_info.downloads
   badge_config = {
       "schemaVersion": 1,
       "label": "Downloads",
       "message": f"{download_count}",
       "color": "blue"
   }
   
   # 保存为JSON文件供徽章调用
   with open("downloads-badge.json", "w") as f:
       json.dump(badge_config, f)
   

3. 配置GitHub Actions定时任务
   在仓库的.github/workflows目录下创建update-downloads.yml工作流文件：

   name: Update Downloads Badge
   on:
     schedule:
       # 每小时自动运行一次，可按需调整频率
       - cron: '0 * * * *'
     workflow_dispatch: # 支持手动触发更新
   
   jobs:
     update-badge:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Set up Python
           uses: actions/setup-python@v5
           with:
             python-version: '3.10'
         - name: Install dependencies
           run: pip install kaggle
         - name: Fetch latest download count
           env:
             KAGGLE_USERNAME: ${{ secrets.KAGGLE_USERNAME }}
             KAGGLE_KEY: ${{ secrets.KAGGLE_KEY }}
           run: python update_downloads.py
         - name: Commit and push changes
           run: |
             git config --global user.name "GitHub Actions"
             git config --global user.email "actions@github.com"
             git add downloads-badge.json
             git commit -m "Update downloads count to $(jq -r '.message' downloads-badge.json)" || exit 0
             git push
   

4. 在README中引入徽章
   在README文件里添加以下代码，替换为你的仓库地址：

   ![Downloads](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/你的用户名/你的仓库名/main/downloads-badge.json)
   

额外说明 #

• 可以修改cron表达式调整更新频率，比如0 */6 * * *表示每6小时更新一次，减少不必要的运行消耗。
• 首次使用可以手动触发GitHub Actions工作流，快速生成初始的下载量徽章。

内容的提问来源于stack exchange，提问作者Umar Masud