# 实例 API v4

> 通过实例 API v4 以编程方式检索、创建、更新或删除 LevelPlay 广告网络实例，从而管理 app 聚合实例。

> **Important:**
>
> API 版本 3 及更低版本从 **2025 年 3 月** 开始弃用。更新到最新版本以避免中断。

使用 Instance API 可以管理 LevelPlay 后台上的实例。此 API 版本支持以下内容：

* 支持 CRUD
* 更改广告网络的应用程序级别配置
* 在瀑布组中添加或删除实例（支持激活的 AB 测试应用程序）

每个调用的请求限制为 1 个应用程序。

## 速率限制##rate-limits

如果请求在 30 分钟内超过 4000 个请求，API 将返回 429 HTTP 状态代码。

## 身份验证类型##authentication-type

[Bearer API 身份验证](/grow/levelplay/platform/api/authentication.md)

## GET##get

### 描述##description

获取所有应用程序实例（竞价和非竞价）的列表。 

### 方法##method

GET [https://platform.ironsrc.com/levelPlay/network/instances/v4/](https://platform.ironsrc.com/levelPlay/network/instances/v4/)

### 请求参数##request-parameters

| Name（名称） | 类型  | 描述                | 示例        |
| -------- | --- | ----------------- | --------- |
| appKey   | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |

### 请求示例 URL##request-example-url

[https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/](https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/)

### 响应参数##response-parameters

| Name（名称）                          | 描述                            | 示例         |
| --------------------------------- | ----------------------------- | ---------- |
| instanceId                        | 唯一实例 ID                       | 1072562    |
| instanceName                      | 实例名称                          | 奖励50       |
| adUnit                            | 每个实例的广告单元类型（奖励视频、插页式广告或横幅广告）  | banner     |
| adFormat                          | 奖励、插页式、横幅广告或原生广告              | 间隙         |
| networkName                       | 实例所属的广告网络                     | adColony   |
| appConfig1/appConfig2             |                               |            |
| instanceConfig1 / instanceConfig2 | 应为每个配置字段发送此信息                 |            |
| isBidder                          | 投标人实例的实例（true 或 false）        | true       |
| 组                                 | 在 LevelPlay 组 API 中发送的组 ID 数组 | 2515, 6226 |
| isLive                            | 实例状态可以是激活或非激活                 | ‘false'    |
| 速率                                | 实例级别速率（如果定义）                  | 15         |

### 响应示例##response-example

```text
[
  {
    "instanceId":1072562,
    "instanceName": "",
    "adUnit": "rewardedVideo",
    "adFormat": "rewarded",
    "networkName": "unityAds",
    "appConfig1": "qtr",
    "instanceConfig1": "trb",
    "isBidder": true,
    "groups": [101663],
    "isLive": true
  },
  {
    "instanceId":1014428,
    "instanceName":"Default",
    "adUnit": "interstitial",
    "adFormat": "interstitial",
    "networkName": "unityAds",
    "appConfig1": "qertb",
    "instanceConfig1": "qtrb",
    "isBidder": false,
    "groups": [101664],
    "isLive": true,
    "rate":25
  },
  {
    "instanceId":1845809,
    "instanceName":"Default",
    "adUnit": "rewardedVideo",
    "adFormat": "rewarded",
    "networkName": "adManager",
    "appConfig1": "bqw",
    "instanceConfig1": "qqr",
    "isBidder": false,
    "groups": [101663 ],
    "isLive": true,
    "rate":4
  }
]

```

## 创建##create

使用此 API 可为聚合广告源创建实例。此 API 允许使用单个 API 调用创建多个实例。请注意，使用 API 创建实例时，您受限于平台允许的实例数量。

使用“组”参数来确定要包含/排除实例的每个瀑布流组。

* 未设置“status”参数创建的实例将自动设置为“激活”
* 为不在应用商店中运行的应用程序创建的实例将自动设置为“非活动”
* 对于具有相同广告网络的实例，应用程序配置必须具有相同的值
* 对于自定义网络实例的创建，需要“networkKey”参数，可在网络文档中找到此参数

### 方法##method

POST [https://platform.ironsrc.com/levelPlay/network/instances/v4/](https://platform.ironsrc.com/levelPlay/network/instances/v4/)

### 请求参数##request-parameters

| Name（名称） | 类型  | 描述                | 示例        |
| -------- | --- | ----------------- | --------- |
| appKey   | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |

### 请求示例 URL##request-example-url

[https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/](https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/)

### 支持的参数##supported-parameters

| Name（名称）        | 类型   | 描述                                                  | 必需          | 示例                    |
| --------------- | ---- | --------------------------------------------------- | ----------- | --------------------- |
| instanceName    | 字符串  | 新创建的实例的名称                                           | ✓ - 对于非竞价实例 | highestBidderinstance |
| networkName     | 字符串  |                                                     | ✓           | adColony              |
| adFormat        | 字符串  | 奖励、插页式、横幅广告或原生广告                                    | ✓           | 间隙                    |
| isBidder        | 布尔值  | 指示实例是否为出价者实例                                        | ✓           | True/False            |
| appConfig1      | 字符串  |                                                     | x           | “123”/“abc”           |
| appConfig2      | 字符串  |                                                     | x           | “123”/“abc”           |
| instanceConfig1 | 字符串  |                                                     | x           | “123”/“abc”           |
| instanceConfig2 | 字符串  |                                                     | x           | “123”/“abc”           |
| 组               | 数字数组 | 如果未发送，则视为“组”。如果正在进行 A/B 测试，建议的最佳做法是为“A”和“B”组roupId。 | x           | 12525                 |
| isLive          | 布尔值  | 使实例激活或非激活。如果未发送，则视为激活                               | x           | True/False            |
| 速率              | 数字   | 0.01-3000 之间                                        | x           | 5                     |

### 请求示例##request-example

```text
[
  {
      "instanceName": "newInstance",     
      "networkName": "unityAds",
      "adUnit": "rewardedVideo",
      "isBidder": true,
      “appConfig1”："414n",
      "instanceConfig1": "aaa1",
      "instanceConfig2": "aaa1",
      "groups": [12345],
      "isLive": true
  },
  {
      "instanceName": "newInstance_2",     
      "networkName": "unityAds",
      "adFormat": "rewarded",
      "isBidder": false,
      “appConfig1”："414n",
      "instanceConfig1": "bbb1",
      "groups": [12345],
      "isLive": true,
      "rate":5
  }
]

```

## 更新##update

使用此 API 可更新实例。通过单个 API 调用即可更新多个实例。

要删除实例级别速率，请添加具有“null”值的速率参数。 

### 方法##method

PUT [https://platform.ironsrc.com/levelPlay/network/instances/v4/](https://platform.ironsrc.com/levelPlay/network/instances/v4/)

### 请求参数##request-parameters

| Name（名称） | 类型  | 描述                | 示例        |
| -------- | --- | ----------------- | --------- |
| appKey   | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |

### 请求示例 URL##request-example-url

[https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/](https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/)

### 支持的参数##supported-parameters

| Name（名称）        | 类型   | 描述                 | 必需 | 示例                    |
| --------------- | ---- | ------------------ | -- | --------------------- |
| instanceId      | 数字   | GET 请求中发送的实例 ID    | ✓  |                       |
| instanceName    | 字符串  | 新创建的实例的名称          | x  | highestBidderinstance |
| appConfig1      | 字符串  |                    | x  | “123”/“abc”           |
| appConfig2      | 字符串  |                    | x  | “123”/“abc”           |
| instanceConfig1 | 字符串  |                    | x  | “123”/“abc”           |
| instanceConfig2 | 字符串  |                    | x  | “123”/“abc”           |
| 组               | 数字数组 | 如果未发送，视为“组”        | x  | 12525                 |
| isLive          | 布尔值  | 激活或非激活。如果未发送，则视为激活 | x  | true                  |
| 速率              | 数字   | 0.01-3000 之间       | x  | 100                   |

### 请求示例##request-example

```text
[
  {
      "instanceId":122,
      "instanceName": "newInstance",
      “appConfig1”："414n",
      "instanceConfig1": "aaa1",
      "instanceConfig2": "aaa1",
      "groups": [1],
      "isLive": true,
      "rate":2
  }
]

```

## 删除##delete

使用此 API 可删除实例。

* 无法删除默认实例。
* 无法恢复已删除的实例。

### 方法##method

删除 [https://platform.ironsrc.com/levelPlay/network/instances/v4/](https://platform.ironsrc.com/levelPlay/network/instances/v4/)

### 请求的参数##requested-parameters

| Name（名称） | 类型  | 描述                | 示例        |
| -------- | --- | ----------------- | --------- |
| appKey   | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |

### 请求示例 URL##request-example-url

[https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/](https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/)

### 支持的参数##supported-parameters

| Name（名称） | 类型   | 描述              | 必需 | 示例         |
| -------- | ---- | --------------- | -- | ---------- |
| id       | 数字数组 | GET 请求中发送的实例 ID | ✓  | 1458, 5769 |

### 请求正文示例##request-body-example

```text
{
    "ids": [1458, 5769]
}

```

## 成功##success

成功响应将随 HTTP 代码 200 一起发送。

## 报错##errors

如果在请求中发送的实例之一失败，则会发送带有 HTTP 代码 400 的报错数组，并导致整个请求被拒绝。

每个报错后都会有报错消息。

### 示例##example

```text
{
    "errorsArray": [
        {
            "code": ERR-402,
            "errorMessage":"实例名称对于相同的广告格式和网络必须唯一",
            "params": {
                "instanceName": "abc"
            }
        }
    ],
    "code": 400
}

```

## API v3（以前版本）##api-v3-(previous-version)

实例 API v3 在实时 A/B 测试期间不支持应用程序。

### 获取实例##get-instances

#### 描述##description

使用此 API 可以检索应用程序的所有实例的列表。响应将包括[应用程序列表 API](/grow/levelplay/platform/api/application.md) 中的所有信息以及以下内容：实例名称、实例 ID、状态和定价（如果相关）（定价仅适用于 ironSource 网络实例）

#### 身份验证类型##authentication-type

[Bearer API 身份验证](/grow/levelplay/platform/api/authentication.md)

#### 方法##method

GET platform.ironsrc.com/partners/publisher/instances/v3?

#### 必需参数##required-parameters

| Name（名称） | 类型  | 描述                |
| -------- | --- | ----------------- |
| appKey   | 字符串 | 应用程序密钥（在我们的平台上显示） |

#### 请求示例 URL##request-example-url

[https://platform.ironsrc.com/partners/publisher/instances/v3?appKey=aa2209b1d](https://platform.ironsrc.com/partners/publisher/instances/v3?appKey=aa2209b1d)

#### 响应参数##response-parameters

| Name（名称）     | 描述                             |
| ------------ | ------------------------------ |
| appKey       | 应用程序密钥（在我们的平台上显示）              |
| appName      | 应用程序名称                         |
| appStatus    | 应用程序状态                         |
| platform     | 平台可以是 iOS 或 Android            |
| bundleId     | 本地 App Store Bundle ID         |
| creationDate | 将 app 添加到 ironSource 平台的日期     |
| id           | ironSource 平台在实例创建时生成的唯一实例 ID  |
| 提供程序实例级别配置\* |                                |
| name         | 实例名称                           |
| status       | 实例状态可以是激活或非激活                  |
| 速率           | 实例级别速率（如果定义）                   |
| 定价           | 在 IronSource 网络平台上设置的定价        |
| abVersion    | A/B 测试版本（可选值为："A", "B", "N/A") |

#### JSON 响应示例##jsonexample-response

```text
{
  "appKey": "aa2209b1d",
  "appName":“My Test app”，
  "appStatus": "active",
  "platform":"Android",
  "bundleId": "com.test.app",
  "creationDate":"N/A",
  "adUnits": {
    "rewardedVideo": {
      "activeNetworks": [
        "ironSource",
        「AdColony」
      ],
      "activeBidderNetworks": [
        ""
      ],
      "networkInstances": {
        "ironSource": [
          {
            "id": 0,
            "name": "Default",
            "status": "active",
            "pricing": [
              {
                "eCPM":"10.5",
                "Countries": [
                  "FR",
                  "英国"
                ]
              }
            ],
            "abVersion":"N/A"
          }
        ],
        "AdColony": [
          {
            "id": 0,
            "zoneId": "zone_ID_US_High",
            "name": "US_high",
            "status": "active",
            "rate":87,
            "abVersion":"N/A"
          },
          {
            "id": 2851429,
            "zoneId": "zone_ID_US_Low",
            "name": "US_Low",
            "status": "active",
            "rate":12,
            "abVersion":"N/A"
          }
        ]
      },
      "networkBidderInstances": []
    },
    "offerWall": {
      "activeNetworks": [
        "ironSource"
      ]
    },
    "interstitial": {
      "activeNetworks": [],
      "activeBidderNetworks": [],
      "networkInstances": {
        "ironSource": [
          {
            "id": 0,
            "name": "Default",
            "status": "inactive",
            "pricing": [
              {
                "eCPM":"8.5",
                "Countries": [
                  "FR",
                  "英国"
                ]
              }
            ],
            "abVersion":"N/A"
          }
        ]
      },
      "networkBidderInstances": []
    },
    "banner": {
      "activeNetworks": [],
      "networkInstances": {
        "ironSource": [
          {
            "id": 0,
            "name": "Default",
            "status": "inactive",
            "abVersion":"N/A"
          }
        ]
      }
    }
  }
}
```

#### 创建实例##create-instances

使用此 API 可为 ironSource 网络和聚合广告源创建实例。此 API 允许使用单个 API 调用创建多个实例。

* 未设置“status”参数创建的实例将自动设置为“激活”
* 为不在应用商店中运行的应用程序创建的实例将自动设置为“非活动”
* 对于聚合用户 - 每个新创建的实例都将包含在 app 的所有[聚合组](/grow/levelplay/platform/best-practices/mediation-management.md)中。
* 每个 app 每个广告单元最多限制 10 个实例。要延长此限制，请[联系支持](https://support-ads.unity.com/s/ContactUs)人员或联系您的帐户经理。
* 要创建投标人网络，请[联系支持](https://support-ads.unity.com/s/ContactUs)人员或联系您的帐户经理。

## CPM 定价##cpmpricing

一般问题

1. CPM 定价 (CPM Pricing) 允许您控制和灵活地定义 LevelPlay 网络的预期 CPM 速率。 在[此处](/grow/levelplay/platform/get-started/instances.md)阅读更多信息。
2. CPM 定价仅适用于指定的帐户。要激活 CPM 定价，请[联系支持](https://support-ads.unity.com/s/ContactUs)人员或联系您的帐户经理。
3. 有关使用定价实例的最佳实践，请访问我们的[最佳实践文章](/grow/levelplay/platform/best-practices/mediation-management.md)。

注意

1. 要为实例设置全局定价，请使用星号角色“\*”填充实例的国家/地区字段。
2. 未定价的实例和未定义定价的国家/地区将被设置为使用优化定价。
3. 根据 ISO 3166-1 Alpha-2，国家/地区定义基于[两个字母](http://www.google.com/url?q=http%3A%2F%2Fwww.iso.org%2Fiso%2Fcountry_names_and_code_elements\&sa=D\&sntz=1\&usg=AFQjCNH80Qqct_9jNAx-Jyv59s1KR-MlSA)的国家/地区代码

### 身份验证类型##authentication-type

[Bearer API 身份验证](/grow/levelplay/platform/api/authentication.md)

### 方法##method

POST platform.ironsrc.com/partners/publisher/instances/v3?

### 必需参数##required-parameters

| Name（名称）     | 类型    | 描述                                        |
| ------------ | ----- | ----------------------------------------- |
| appKey       | 字符串   | 应用程序密钥（在我们的平台上显示）                         |
| 提供商          | 字符串数组 |                                           |
| adUnit       | 字符串数组 | "rewardedVideo", "interstitial", "banner" |
| instanceName | 字符串   | 新创建的实例的名称                                 |
| 提供程序实例级别配置\* | 字符串   |                                           |

> **Note:**
>
> 只有在创建聚合音频源实例时，提供程序实例级别配置是必需的。此参数命名因聚合广告源而异。

### 可选参数##optionalparameters

| Name（名称）       | 类型    | 描述                        |
| -------------- | ----- | ------------------------- |
| status         | 字符串   | 实例状态可以是“激活”或“非激活”         |
| 定价             | 字符串数组 | 确定 ironSource 网络要交付的 eCPM |
| 速率             | 双倍    | 实例级别速率（如果定义）              |
| 提供商 app 级别配置\* | 字符串   |                           |

> **Note:**
>
> 广告音频源app级别配置因聚合广告源而异。

### 请求示例网址##requestexampleurl

`https://platform.ironsrc.com/partners/publisher/instances/v3`

### 请求示例正文##requestexample-body

```text
{
  "appKey": "d11a21a5",
  "configurations": {
    "ironSource": {
      "interstitial": [
        {
          "instanceName": "low_interstitial",
          "status": "active",
          "pricing": [
            {
              "country": [
                "FR",
                "DE"
              ],
              "eCPM":3
            }
          ],
          "pricingType": "eCPM"
        },
        {
          "instanceName": "high_interstitial",
          "status": "active",
          "pricing": [
            {
              "country": [
                "IL",
                “US”
              ],
              "eCPM":20
            }
          ]
        }
      ]
    },
    "adColony": {
      "rewardedVideo": [
        {
          "instanceName": "adcolony_rv",
          "status": "active",
          "zoneId":102030,
          "rate":10
        }
      ]
    }
  }
}
```

### JSON 响应示例##jsonexample-response

```text
{
  "rewardedVideo": {
    "AdColony": [
      {
        "id": 6701121,
        "zoneId":"102030",
        "name": "adcolony_rv",
        "status": "active",
        "rate":10,
        "abVersion":"N/A"
      }
    ]
  },
  "interstitial": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "active",
        "abVersion":"N/A"
      },
      {
        "id": 6701117,
        "name": "low_interstitial",
        "status": "active",
        "abVersion":"N/A",
        "pricing": [
          {
            "eCPM":3,
            "Countries": [
              "FR",
              "DE"
            ]
          }
        ]
      },
      {
        "id": 6701119,
        "name": "high_interstitial",
        "status": "active",
        "abVersion":"N/A",
        "pricing": [
          {
            "eCPM":20,
            "Countries": [
              "IL",
              “US”
            ]
          }
        ]
      }
    ],
    "ironSourceBidding": [
      {
        "id": 2948695,
        "name": "",
        "status": "inactive",
        "abVersion":"N/A"
      }
    ]
  }
}
```

#### 更新实例##update-instances

使用此 API 可更新 IronSource 网络和聚合广告源的实例名称、状态和定价（定价仅适用于 ironSource 网络）。通过单个 API 调用即可更新多个实例。

* 更新调用的最大数量限制为每天 6 次。
* 为了激活非默认实例，必须首先激活默认实例（实例 ID=0）。
* 更新实例定价将仅替换同一实例上的所有定价值。
* 要更新投标人网络，请[联系支持](https://support-ads.unity.com/s/ContactUs)人员或联系您的帐户经理。
* 要删除实例级别速率，请添加具有空字字符串值的 速率 参数（例如“

### 身份验证类型##authentication-type

[Bearer API 身份验证](/grow/levelplay/platform/api/authentication.md)

### 方法##method

PUT platform.ironsrc.com/partners/publisher/instances/v3?

### 必需参数##required-parameters

| Name（名称）   | 类型    | 描述                                        |
| ---------- | ----- | ----------------------------------------- |
| appKey     | 字符串   | 应用程序密钥（在我们的平台上显示）                         |
| 提供商        | 字符串数组 |                                           |
| adUnit     | 字符串数组 | "rewardedVideo", "interstitial", "banner" |
| instanceId | 字符串   | ironSource 平台在实例创建时生成的 ID                 |

### 可选参数##optionalparameters

| Name（名称）     | 类型  | 描述                        |
| ------------ | --- | ------------------------- |
| name         | 字符串 | 实例的名称                     |
| 定价           | 字符串 | 确定 ironSource 网络要交付的 eCPM |
| status       | 字符串 | 实例状态可以是“激活”或“非激活”         |
| 速率           | 双倍  | 实例级别速率（如果定义）              |
| 提供程序实例级别配置\* | 字符串 |                           |
| 提供商app级别配置\* | 字符串 |                           |

> **Note:**
>
> 提供商 app 和实例级别配置命名因聚合广告源而异。

### 请求示例网址##requestexampleurl

[https://platform.ironsrc.com/partners/publisher/instances/v3](https://platform.ironsrc.com/partners/publisher/instances/v3)?

### 请求正文示例##request-body-example

```text
{
  "appKey":"6bc83099",
  "configurations": {
    "ironSourceBidding": {
      "rewardedVideo": [
        {
          "instanceId":327,
          "status": "inactive"
        }
      ]
    }
  }
}
```

### JSON 响应示例##jsonresponse-example

```text
{
  "rewardedVideo": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "inactive",
        "abVersion":"N/A"
      }
    ],
    "AdColony": [
      {
        "id": 0,
        "name": "default",
        "status": "active",
        "abVersion":"N/A"
      },
      {
        "id": 326,
        "name": "lw",
        "status": "inactive",
        "rate":"2",
        "abVersion":"N/A"
      }
    ],
    "ironSourceBidding": [
      {
        "id": 327,
        "name": "-",
        "status": "inactive",
        "abVersion":"N/A"
      }
    ]
  },
  "interstitial": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "active",
        "abVersion":"N/A"
      }
    ]
  },
  "banner": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "inactive",
        "abVersion":"N/A"
      }
    ]
  }
}
```

## 删除实例##deleteinstance

### 描述##description

使用此 API 可删除实例。

一般注意事项：

1. 每次调用可以删除一个实例。
2. 无法删除默认实例。
3. 无法恢复已删除的实例。
4. Response 包含 app 的所有实例（已删除的实例除外）。

### 身份验证类型##authentication-type

[Bearer API 身份验证](/grow/levelplay/platform/api/authentication.md)

### 方法##method

DELETE platform.ironsrc.com/partners/publisher/instances/v3?

### 必需参数##required-parameters

| Name（名称）   | 类型  | 描述                        |
| ---------- | --- | ------------------------- |
| appKey     | 字符串 | 应用程序密钥（在我们的平台上显示）         |
| instanceId | 字符串 | ironSource 平台在实例创建时生成的 ID |

### 请求示例网址##requestexample-url

[http://platform.ironsrc.com/partners/publisher/instances/v3?appKey=6e9e4c11\\\&instanceId=12345](http://platform.ironsrc.com/partners/publisher/instances/v3?appKey=6e9e4c11\\\&instanceId=12345)

### JSON 响应示例##jsonresponse-example

```text
{
  "rewardedVideo": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "active"
      },
      {
        "id": 45678,
        "name": "thirdRVInstance",
        "status": "inactive"
      }
    ]
  },
  "interstitial": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "active"
      },
      {
        "id": 23456,
        "name": "secondISInstance",
        "status": "active",
        "pricing": [
          {
            "eCPM":"0.01",
            "Countries": [
              "FR",
              "英国"
            ]
          }
        ]
      }
    ]
  },
  "banner": {
    "ironSource": [
      {
        "id": 0,
        "name": "Default",
        "status": "inactive"
      }
    ]
  }
}
```