Home/Treatment Management/Insert Surface

Insert Surface

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

API定義

POST https://apis.auxia.io/v1/InsertSurface

注記

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

エンティティ

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（大文字・小文字を問わず）

ヒント

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

注意

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を作成するたびに実行しても問題ありません。