> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auxia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert Surface

> API for registering a Surface via API.

<Note>
  日本語版はAIによる翻訳です。正確な情報については[英語版](/api-reference/treatment-management/insert-surface)をご参照ください。
</Note>

このドキュメントでは、APIを通じてSurfaceを直接登録できるInsertSurface RPCのガイドと概要を提供します。Surfaceは、`InsertTreatmentType`や`UpdateTreatmentType`で名前を指定して参照する前に存在している必要があります。本エンドポイントにより、API主導のTreatment Type連携において、これまで必要だったコンソールでの手動登録が不要になります。

## API定義

```url theme={null}
POST https://apis.auxia.io/v1/InsertSurface
```

<Note>
  `InsertSurface`の呼び出しには**Treatment Management**のAPIキーが必要で、`x-api-key`ヘッダーで渡します。Treatment Management権限のないキーは`403 PERMISSION_DENIED`で拒否されます。APIキーはリクエストの`projectId`に対して検証されるため、あるプロジェクト向けに発行されたキーで別のプロジェクトにSurfaceを作成することはできません。
</Note>

## エンティティ

### SurfacePb

```
message SurfacePb {
  // The Surface name. Surfaces are referenced by name everywhere in the API,
  // so there is no separate Auxia-side identifier to store.
  string surface_name = 1;
}
```

## InsertSurface

### Surfaceを登録するAPI

```
message InsertSurfaceRequest {
  // Required.
  // Numeric project id.
  string project_id = 1;

  // Required.
  // Must match ^[A-Za-z][A-Za-z0-9_]*$, with a maximum length of 200 characters.
  // Cannot be "All" in any casing.
  string surface_name = 2;

  // Required.
  // Identifies who made the change, for audit purposes. Typically an email address.
  string last_modified_by = 3;
}

message InsertSurfaceResponse {
  // The registered Surface (or the pre-existing one, if it already existed).
  SurfacePb surface = 1;
}
```

### Surface名のルール

| ルール  | 内容                            |
| ---- | ----------------------------- |
| パターン | `^[A-Za-z][A-Za-z0-9_]*$`     |
| 先頭文字 | 英字である必要があります。数字で始まる名前は拒否されます。 |
| 使用可能 | 大文字、小文字、数字（先頭を除く）、アンダースコア     |
| 使用不可 | ハイフン、スペース、その他の記号              |
| 最大長  | 200文字                         |
| 予約語  | `All`（大文字・小文字を問わず）            |

<Tip>
  InsertSurfaceは`(project_id, surface_name)`に対して冪等です。同じプロジェクトと名前で再度呼び出した場合、重複を作成することもエラーを返すこともなく、既存のSurfaceを返します。そのため、ネットワークタイムアウト後の再送は常に安全であり、どのSurfaceを作成済みかを管理する必要はありません。Surfaceを名前で参照する前に、無条件に呼び出してください。
</Tip>

:::caution
Surfaceは削除できません。作成時には、そのSurfaceに紐づくイベントスキーマとデータフィールドも合わせて作成されます。名前を誤るとそのSurfaceが永続的に残るため、呼び出し前に名前を検証してください。
:::

### cURLリクエストのサンプル

```
curl --location --request POST 'https://apis.auxia.io/v1/InsertSurface' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
  "projectId": "PROJECT_ID",
  "surfaceName": "IN_APP_CONTENT",
  "lastModifiedBy": "USER_EMAIL"
}'
```

### レスポンスのサンプル

```
{
  "surface": {
    "surfaceName": "IN_APP_CONTENT"
  }
}
```

### エラー

| HTTP | 条件                                                         |
| ---- | ---------------------------------------------------------- |
| 400  | `surfaceName`が必須パターンに一致しない場合（先頭が数字、ハイフンを含むなど）              |
| 400  | `surfaceName`が予約語`All`である場合（大文字・小文字を問わず）                   |
| 400  | `surfaceName`または`lastModifiedBy`が空、あるいは`projectId`が数値でない場合 |
| 403  | APIキーにTreatment Management権限がない場合                          |
| 403  | APIキー自体は有効だが、別のプロジェクトに属している場合                              |
| 403  | APIキーが指定されていない場合                                           |

## SurfaceとTreatment Typeを合わせて登録する

`InsertTreatmentType`と`UpdateTreatmentType`は、`surfaces`で指定されたすべてのSurfaceがそのプロジェクトに既に存在することを検証し、存在しない場合は`400`でリクエストを拒否します。

```
{"code":400,"message":"The following surfaces do not exist for project_id PROJECT_ID: IN_APP_CONTENT"}
```

まず各Surface名に対して`InsertSurface`を呼び出し、その後Treatment Typeのリクエストでそれらの名前を参照してください。

1. Treatment Typeで使用する各Surfaceについて`POST /v1/InsertSurface`を呼び出す
2. `surfaces: [{ "surfaceName": "IN_APP_CONTENT" }]`を指定して`POST /v1/InsertTreatmentType`を呼び出す
3. `POST /v1/InsertTreatment`でTreatment Typeにコンテンツを追加する

ステップ1は冪等であるため、Surfaceを初めて使用するときだけでなく、Treatment Typeを作成するたびに実行しても問題ありません。