Relevant source files

The following files were used as context for generating this wiki page: - [utils/ampapi/album.go](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/album.go) - [utils/ampapi/artist.go](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/artist.go) - [utils/ampapi/song.go](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/song.go) - [utils/ampapi/token.go](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/token.go) - [config.yaml](https://github.com/zhaarey/apple-music-downloader/blob/main/config.yaml) [FILE_URLS] (use these URLs when citing sources in the content): - utils/ampapi/album.go: https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/album.go - utils/ampapi/artist.go: https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/artist.go - utils/ampapi/song.go: https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/song.go - utils/ampapi/token.go: https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/token.go - config.yaml: https://github.com/zhaarey/apple-music-downloader/blob/main/config.yaml

# API实现本页阐述 **Apple Music Downloader** 项目中对 Apple Music Catalog API（AMP API）的实现细节。核心功能包括： * 自动获取 **Bearer token**（`GetToken`） * 根据 **storefront、ID、语言** 调用 **Album** 与 **Song** 接口获取完整的元数据 * 通过 **分页** 机制递归抓取专辑全部曲目这些实现为后续的下载、封面、歌词、转码等模块提供统一、可靠的数据来源。 --- ## 目录 1. [Token 获取机制](#token-获取机制) 2. [Album API 实现](#album-api-实现) 3. [Song API 实现](#song-api-实现) 4. [配置项与运行时行为](#配置项与运行时行为) 5. [数据结构概览](#数据结构概览) 6. [调用流程图](#调用流程图) 7. [类/结构体关系图](#类结构体关系图) 8. [关键函数表](#关键函数表) 9. [结论](#结论) --- ## Token 获取机制 `utils/ampapi/token.go` 实现了 **动态抓取** Apple Music 前端页面中嵌入的 JWT。步骤： 1. **请求首页** `https://music.apple.com`，解析返回的 HTML，定位 `index~*.js` 脚本路径。 2. **请求该 JS**，使用正则 `eyJh([^"]*)` 抽取 JWT（即 `Authorization` token）。此 token 可直接用于后续 API 调用的 `Authorization: Bearer ` 头部。若调用时未显式提供 token，`GetAlbumResp` 与 `GetSongResp` 会自动调用 `GetToken`。 > **安全提示**：该 token 为公开的前端 token，使用时仍需遵守 Apple 的使用条款。 **代码片段**（关键实现）： ```go func GetToken() (string, error) { // 1. 获取首页 req, _ := http.NewRequest("GET", "https://music.apple.com", nil) resp, _ := http.DefaultClient.Do(req) body, _ := io.ReadAll(resp.Body) // 2. 解析 index.js 路径 regex := regexp.MustCompile(`/assets/index~[^/]+\.js`) indexJsUri := regex.FindString(string(body)) // 3. 请求 index.js 并抽取 token req, _ = http.NewRequest("GET", "https://music.apple.com"+indexJsUri, nil) resp, _ = http.DefaultClient.Do(req) body, _ = io.ReadAll(resp.Body) tokenRegex := regexp.MustCompile(`eyJh([^"]*)`) token := tokenRegex.FindString(string(body)) return token, nil } ``` Sources: [token.go](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/token.go) --- ## Album API 实现 `GetAlbumResp` 与 `GetAlbumRespByHref` 位于 `utils/ampapi/album.go`，负责： | 步骤 | 说明 | |------|------| | **Token 检查** | 若 `token` 参数为空，调用 `GetToken` 自动获取。 | | **构造请求** | `GET https://amp-api.music.apple.com/v1/catalog/{storefront}/albums/{id}`，并附加查询参数：
`omit[resource]=autos`、`include=tracks,artists,record-labels`、`extend=editorialVideo,extendedAssetUrls`、`l={language}` | | **发送请求** | 使用 `http.DefaultClient.Do`，检查 `200 OK`。 | | **解析响应** | JSON 反序列化为 `AlbumResp`。 | | **分页抓取** | 若 `Relationships.Tracks.Next` 不为空，循环请求 `next` URL（同样带 `omit[resource]`、`include=artists`、`extend=editorialVideo,extendedAssetUrls`），将返回的 `TrackResp.Data` 合并到原始 `AlbumResp.Data[0].Relationships.Tracks.Data` 中，直至 `next` 为空。 | ### 关键结构体 * `AlbumResp` – 包含 `Href`、`Next` 与 `Data`（专辑主信息）。 * `AlbumRespData` – 专辑属性（封面、艺术家、发行日期等）以及 `Relationships`（艺术家、唱片公司、曲目）。 * `TrackResp`（在同文件中未显式定义，但在分页逻辑中使用） – 用于承载单页曲目列表及 `Next` 链接。 **代码片段**（分页循环）： ```go if len(obj.Data[0].Relationships.Tracks.Next) > 0 { next := obj.Data[0].Relationships.Tracks.Next for { req, _ := http.NewRequest("GET", fmt.Sprintf("https://amp-api.music.apple.com%s", next), nil) // set headers … do, _ := http.DefaultClient.Do(req) obj2 := new(TrackResp) json.NewDecoder(do.Body).Decode(&obj2) obj.Data[0].Relationships.Tracks.Data = append( obj.Data[0].Relationships.Tracks.Data, obj2.Data...) next = obj2.Next if len(next) == 0 { break } } } ``` Sources: [album.go:1-120](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/album.go) --- ## Song API 实现 `GetSongResp` 位于 `utils/ampapi/song.go`，实现单曲元数据获取。流程与专辑类似，但 **不涉及分页**，因为单曲响应已完整。 | 步骤 | 说明 | |------|------| | **Token 检查** | 同专辑 API，缺省时调用 `GetToken`。 | | **请求 URL** | `GET https://amp-api.music.apple.com/v1/catalog/{storefront}/songs/{id}` | | **查询参数** | `include=albums,artists`、`extend=extendedAssetUrls`、`l={language}` | | **响应结构** | `SongResp` 包含 `Previews`（试听 URL）、`Artwork`、`ExtendedAssetUrls`（HLS 链接）等。 | **代码片段**（核心请求）： ```go req, _ := http.NewRequest("GET", fmt.Sprintf("https://amp-api.music.apple.com/v1/catalog/%s/songs/%s", storefront, id), nil) req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", token)) query := url.Values{} query.Set("include", "albums,artists") query.Set("extend", "extendedAssetUrls") query.Set("l", language) req.URL.RawQuery = query.Encode() ``` Sources: [song.go:1-80](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/song.go) --- ## 配置项与运行时行为 `config.yaml` 定义了下载器的全局行为。与 API 实现直接关联的字段： | 配置键 | 作用 | 关联代码/说明 | |--------|------|---------------| | `authorization-token` | 预置的 **Bearer token**（可手动填写） | 若为空，`GetAlbumResp`/`GetSongResp` 会调用 `GetToken` 自动获取。 | | `language` | API 请求的语言参数 `l` | 通过 `GetAlbumResp`、`GetSongResp` 的 `language` 参数传递。 | | `storefront` | 两字母国家码，用于构造 API 路径 | 需要在调用方（如 CLI）传入 `storefront` 参数。 | | `media-user-token` | 用于获取歌词、AAC‑LC 等受限资源（本文件未在源码中直接使用） | 未来可能在歌词/音频下载模块中引用。 | > **注意**：`config.yaml` 中的 `authorization-token` 默认提示 “可以自动获取”，因此大多数情况下用户无需手动配置。 --- ## 数据结构概览 | 结构体 | 所属文件 | 关键字段 | 说明 | |--------|----------|----------|------| | `AlbumResp` | album.go | `Href`, `Next`, `Data[]` | 专辑根响应 | | `AlbumRespData` | album.go | `Attributes`（封面、艺术家、发行信息）
`Relationships`（曲目、艺术家、唱片公司） | 单个专辑的详细信息 | | `SongResp` | song.go | `Previews`, `Artwork`, `ExtendedAssetUrls`, `Attributes` | 单曲完整元数据 | | `TrackResp` | album.go（分页使用） | `Data[]`, `Next` | 专辑曲目分页结果 | | `Token`（隐式） | token.go | `token`（JWT） | 用于 Authorization 头部 | --- ## 调用流程图下面的 **flowchart** 展示了从 **入口函数**（如 CLI）到 **获取完整专辑/单曲信息** 的完整路径，包括 **Token 自动获取** 与 **分页循环**。 ```mermaid graph TB startNode[Start] --> checkToken{Need token?} checkToken -->|Yes| tokenNode[GetToken#40;#41;] tokenNode --> tokenOk[Token obtained] tokenOk --> apiChoice{API type} apiChoice -->|Album| albumCall[Call Album API#40;storefront#47;id#41;] apiChoice -->|Song| songCall[Call Song API#40;storefront#47;id#41;] albumCall --> albumResp[AlbumResp received] albumResp --> pagination{Has next page?} pagination -->|Yes| nextPage[Fetch next Track page] nextPage --> pagination pagination -->|No| albumDone[Album data complete] songCall --> songResp[SongResp received] songResp --> songDone[Song data ready] albumDone --> endNode[End] songDone --> endNode ``` > **说明** > * `GetToken#40;#41;` 表示调用 `GetToken()`。 > * `Call Album API#40;storefront/id#41;` 表示 `GetAlbumResp`（或 `GetAlbumRespByHref`）的请求。 > * `Has next page?` 对应 `Relationships.Tracks.Next` 的循环逻辑。 --- ## 类/结构体关系图 ```mermaid classDiagram class AlbumResp { +string Href +string Next +AlbumRespData[] Data } class AlbumRespData { +string ID +string Type +string Href +Attributes Attributes +Relationships Relationships } class SongResp { +string Href +string Next +SongRespData[] Data } class SongRespData { +string ID +string Type +string Href +Attributes Attributes } class TrackResp { +TrackData[] Data +string Next } AlbumResp --> AlbumRespData : contains AlbumRespData --> Attributes : has AlbumRespData --> Relationships : has SongResp --> SongRespData : contains AlbumRespData --> TrackResp : uses for tracks ``` > **注意**：`TrackResp` 在 `album.go` 中未显式声明，但在分页实现中被实例化，故在图中标注。 --- ## 关键函数表 | 函数 | 所在文件 | 参数 | 返回值 | 主要功能 | |------|----------|------|--------|----------| | `GetToken` | token.go | 无 | `(string, error)` | 抓取前端 JS，提取 JWT | | `GetAlbumResp` | album.go | `storefront string, id string, language string, token string` | `(*AlbumResp, error)` | 获取专辑主信息并递归抓取全部曲目 | | `GetAlbumRespByHref` | album.go | `href string, language string, token string` | `(*AlbumResp, error)` | 通过已知 href（不含 storefront）获取专辑 | | `GetSongResp` | song.go | `storefront string, id string, language string, token string` | `(*SongResp, error)` | 获取单曲完整元数据 | | `new(http.Request)` | 标准库 | — | — | 用于构造 HTTP 请求（在所有 API 实现中重复使用） | **示例调用**（获取专辑并打印曲目数）： ```go album, err := GetAlbumResp("us", "123456789", "en-US", "") if err != nil { log.Fatal(err) } fmt.Printf("Album %s has %d tracks\n", album.Data[0].Attributes.Name, len(album.Data[0].Relationships.Tracks.Data)) ``` Sources: [album.go:1-120](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/album.go), [song.go:1-80](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/song.go), [token.go:1-70](https://github.com/zhaarey/apple-music-downloader/blob/main/utils/ampapi/token.go) --- ## 结论 Apple Music Downloader 的 **API 实现** 通过以下关键点实现了可靠的数据获取： 1. **动态 Token 获取**：无需手动维护 token，`GetToken` 自动抓取最新 JWT。 2. **统一请求封装**：所有请求均使用相同的 Header（`Authorization`, `User-Agent`, `Origin`），确保与浏览器行为一致。 3. **分页递归**：专辑曲目通过 `Relationships.Tracks.Next` 循环抓取，保证完整性。 4. **配置驱动**：`config.yaml` 中的 `storefront`、`language` 与 `authorization-token` 直接影响 API 调用，便于跨地区、跨语言使用。这些实现为后续的 **下载、封面、歌词、转码** 等功能提供了坚实的基础，使得整个下载器能够在不同地区、不同语言环境下保持一致的行为。