asc-availability

用途

asc-availability 用于管理 App Store 地区（国家/地区）可用性，覆盖三类对象：应用（App）、内购（IAP）和订阅（Subscription）。它可以帮助开发者控制区域分发，例如了解应用为何在特定国家被阻止销售、将订阅限制在指定市场，或让某个内购在全球开放。

主要能力

应用可用性（按地区状态）

最完整的可用性视图，展示每个地区的 isAvailable（true/false）、通过 contentStatuses 给出的阻止原因、releaseDate 以及 isPreOrderEnabled。

asc app-availability get --app-id <APP_ID> [--pretty]

如果应用的可用性从未设置过（App Store Connect 显示 Set Up Availability），该命令返回 {"data":[]} 并打印提示。设置方式：

asc app-availability create --app-id <APP_ID> --all-territories --available-in-new-territories
asc app-availability create --app-id <APP_ID> --territory USA --territory JPN [--available-in-new-territories]

可通过重复的 --territory 指定地区，或使用 --all-territories（取自 asc territories list 的全部地区）。REST 接口为 POST /api/v1/apps/:appId/availability，请求体为 {"territory": [...]} 或 {"all-territories": true}。未发布的应用在每个地区都会显示 CANNOT_SELL + AVAILABLE_FOR_SALE_UNRELEASED_APP，这在发布前属于预期现象。

该视图会返回全部约 175 个地区及其状态。contentStatuses 的关键值包括：

AVAILABLE — 正常销售
CANNOT_SELL_RESTRICTED_RATING — 年龄分级导致该地区无法销售
MISSING_RATING — 未配置年龄分级
ICP_NUMBER_MISSING — 中国要求 ICP 备案号
BRAZIL_REQUIRED_TAX_ID — 巴西要求税号
CANNOT_SELL_GAMBLING / CANNOT_SELL_CASINO — 博彩限制
另有 30 多种具体阻止原因

列出所有地区

在设置可用性之前，需要先获取有效的地区 ID。Apple 约有 175 个地区，每个地区有 ISO 风格的 ID（如 USA、CHN、JPN）和货币代码。

asc territories list [--output table] [--pretty]

示例输出：

ID    Currency
USA   USD
CHN   CNY
JPN   JPY
GBR   GBP
DEU   EUR
...

内购可用性

获取当前内购可用性，查看某个内购目前在哪些地区可用，响应中包含每个地区的货币代码：

asc iap-availability get --iap-id <IAP_ID> [--pretty]

示例 JSON 响应：

{
  "data": [
    {
      "id": "avail-1",
      "iapId": "iap-42",
      "isAvailableInNewTerritories": true,
      "territories": [
        { "id": "USA", "currency": "USD" },
        { "id": "CHN", "currency": "CNY" }
      ],
      "affordances": {
        "getAvailability": "asc iap-availability get --iap-id iap-42",
        "createAvailability": "asc iap-availability create --iap-id iap-42 ...",
        "listTerritories": "asc territories list"
      }
    }
  ]
}

创建内购可用性，设置某个内购应在哪些地区可用。使用 --territory（可重复）指定地区 ID，--available-in-new-territories 自动包含 Apple 未来新增的地区：

asc iap-availability create \
  --iap-id <IAP_ID> \
  --available-in-new-territories \
  --territory USA \
  --territory CHN \
  --territory JPN

标志说明：

--iap-id：必填，要设置可用性的内购 ID
--available-in-new-territories：可选，自动包含 Apple 新增的地区
--territory：可选，地区 ID（可重复），可用 asc territories list 查找有效 ID

订阅可用性

获取当前订阅可用性：

asc subscription-availability get --subscription-id <SUB_ID> [--pretty]

创建订阅可用性：

asc subscription-availability create \
  --subscription-id <SUB_ID> \
  --available-in-new-territories \
  --territory USA \
  --territory GBR

标志说明：

--subscription-id：必填，要设置可用性的订阅 ID
--available-in-new-territories：可选，自动包含 Apple 新增的地区
--territory：可选，地区 ID（可重复）

CAEOAS Affordances

每个可用性响应都包含可直接运行的后续命令：

{
  "affordances": {
    "getAvailability": "asc iap-availability get --iap-id <ID>",
    "createAvailability": "asc iap-availability create --iap-id <ID> ...",
    "listTerritories": "asc territories list"
  }
}

InAppPurchase 和 Subscription 模型也包含 getAvailability affordance，便于从父资源导航。

解析 App ID

见 project-context.md —— 在询问用户或运行 asc apps list 之前，先检查 .asc/project.json。

典型工作流

APP_ID=$(cat .asc/project.json 2>/dev/null | jq -r '.appId // empty')

# 1. 发现地区
asc territories list --output table

# 2. 列出应用的 IAP
asc iap list --app-id "$APP_ID"

# 3. 查看当前可用性
asc iap-availability get --iap-id "$IAP_ID" --pretty

# 4. 设置到指定地区，并自动包含未来新增地区
asc iap-availability create --iap-id "$IAP_ID" \
  --available-in-new-territories \
  --territory USA --territory GBR --territory DEU --territory JPN

# 订阅流程相同：
asc subscriptions list --group-id "$GROUP_ID"
asc subscription-availability get --subscription-id "$SUB_ID"
asc subscription-availability create --subscription-id "$SUB_ID" \
  --available-in-new-territories \
  --territory USA --territory CHN

关键概念

Territory ID：App Store Connect 使用的 ISO 风格国家代码（如 USA、CHN、JPN、GBR）。使用 asc territories list 查看所有有效 ID。
isAvailableInNewTerritories：为 true 时，Apple 会自动让该 IAP/订阅在其新增的任何地区可用。除非需要严格的区域控制，否则建议大多数应用启用。
Currency：每个地区都有对应的货币（如 USD、CNY）。可用性响应中会在地区 ID 旁显示，便于了解定价背景。

适用场景

适合需要通过命令行批量管理 App Store 区域分发、排查地区屏蔽原因、精细化控制内购或订阅市场范围的开发者。

限制

关于具体依赖版本、鉴权配置、asc CLI 安装方式与平台支持等信息，资料未提供。