クイックスタート

このページでは、Hane の上にアプリを作り始めるまでの最短の手順を説明します。API キーを用意して SDK で公開 API を呼び、hanectl で型の定義を入れ、作ったレコードをコンソールで確かめます。

始める前に

• Node.js 22.13 以上
• 組織とプロジェクト。組織の管理者（owner か admin のロール）が用意します
• Hane の入口の URL。このページでは環境変数 HANE_API に入れておきます

ヒント

手元で試すなら、ローカル開発 の pnpm dev と pnpm dev:seed で、作りものの組織 acme・プロジェクト fleet・API キーまで一度にそろいます。入口の URL は http://localhost:8787 です。

手順

1. サービスアカウントと API キーを用意する

   アプリは、人でない呼出し元であるサービスアカウントとして Hane を呼びます。サービスアカウントはプロジェクトと環境に結び付き、スコープは作るときに決めて後から変えられません。管理者のアクセストークン（hanectl token で表示できます）で、次のように作ります。

   import { createHaneClient, unwrap } from "@hane/sdk";
   
   const admin = createHaneClient({ baseUrl: process.env.HANE_API!, token: () => process.env.ADMIN_TOKEN ?? null });
   
   const sa = await unwrap(
     admin.POST("/v1/platform/service-accounts", {
       body: {
         name: "quickstart",
         project: "fleet",
         environment: "dev",
         scopes: ["data:schemas.read", "data:records.read", "data:records.write", "definitions:read", "definitions:apply", "definitions:release"],
       },
     }),
   );
   const key = await unwrap(admin.POST("/v1/platform/service-accounts/{id}/keys", { params: { path: { id: sa.sa_id } } }));
   console.log(key.secret); // hane_dev_... この応答でしか読めない

   API キーは、コンソールの「アクセス」→「サービスアカウントと API キー」でも発行と失効ができます。値は .env などに置き、Git に入れないでください。

2. SDK を入れる プレビュー

   TypeScript の SDK @hane/sdk を、アプリの依存に加えます。SDK は openapi-fetch の上の薄いクライアントで、ブラウザと Node.js の両方で動きます。パッケージはまだ公開のレジストリには載せていないので、入手の方法は提供元に確認してください。ほかの言語から呼ぶときは、API リファレンス の OpenAPI を使えます。

3. 公開 API を呼ぶ

   API キーを token に渡してクライアントを作り、有効なバージョンの型の一覧を読みます。

   import { createHaneClient, unwrap } from "@hane/sdk";
   
   const hane = createHaneClient({
     baseUrl: process.env.HANE_API!,
     token: () => process.env.HANE_API_KEY ?? null,
   });
   
   const { types } = await unwrap(hane.GET("/v1/data/types"));
   console.log(types.map((t) => t.type)); // まだ定義がなければ空

4. hanectl でログインする

   hanectl は、定義とプロジェクトを操作する CLI です。API キーでログインすると、その組織・プロジェクト・環境が今の context になります。

   hanectl login --api-key "$HANE_API_KEY" --org acme --project fleet --env dev --server "$HANE_API"

5. 定義を書いて apply する

   definitions/schemas/vehicle.yaml に型を書き、同じディレクトリの bundle.yaml に、ReleaseBundle に束ねる範囲を書きます。

   definitions/schemas/vehicle.yaml

   apiVersion: data/v1alpha1
   kind: Schema
   metadata:
     name: vehicle
   spec:
     type: Vehicle
     key: registration_no
     display: registration_no
     fields:
       registration_no: { type: string, title: 登録番号 }
       model: { type: string, title: 車種 }
       inspection_expiry: { type: string, format: date, title: 車検の満了日 }
     required: [registration_no]

   definitions/bundle.yaml

   apiVersion: release/v1alpha1
   kind: Bundle
   metadata:
     name: quickstart
   spec:
     resources:
       - schemas/

   hanectl validate -f definitions   # 手元で形と参照を確かめる
   hanectl diff -f definitions       # apply で何が変わるかを見る
   hanectl apply -f definitions      # draft として保存する（まだ効かない）

6. ReleaseBundle を作って有効にする

   draft は、ReleaseBundle にして有効にしたときに効きます。

   hanectl release create -f definitions/bundle.yaml --activate

7. レコードを作ってコンソールで見る

   SDK でレコードを 1 件作ります。値は { value } の形で渡します。

   const record = await unwrap(
     hane.POST("/v1/data/records", {
       body: {
         type: "Vehicle",
         values: {
           registration_no: { value: "架空 300 あ 10-01" },
           model: { value: "バン" },
           inspection_expiry: { value: "2027-03-31" },
         },
       },
     }),
   );
   console.log(record.id, record.values.inspection_expiry?.state);

   コンソールにログインし、「定義とリリース」で有効になった ReleaseBundle を確かめます。データの画面では、作ったレコードと値の状態が見られます。

注意

このページでは手順を短くするため、1 つのサービスアカウントに定義を変えるスコープ（definitions:apply・definitions:release）も持たせました。実際のアプリでは、アプリの実行に使うサービスアカウントと、定義を入れる CI のサービスアカウントを分けてください。prod の有効化は、人が自分のログインで行います。

次に読む

アプリの構成画面・BFF・SDK・定義をどう分けるか

認証API キー、アクセストークン、トークン交換、スコープ

マニフェストを書く定義の種類、ファイルの置き方、CEL

参照アプリのチュートリアル車両リース管理を動かして読む