#DevBase

DevBase は、アプリケーションのエンドユーザーを管理する無料のディレクトリです。独自のユーザーを登録し、Connect API を通じて検索、変更できます。ユーザーは Delino アカウントを必要とせず、アプリケーションは独自のログインを引き続き使用します。DevBase は各ユーザーに安定した ID を付与し、その ID を他のサービスに渡せます。

#概念

• テナント: Delino の個人スペースまたは組織です。Delcore がテナントとそのメンバーを管理します。
• プロジェクト: テナント内にある、名前付きのエンドユーザーディレクトリです。同じテナント内であっても、プロジェクト間でユーザーは共有されません。
• エンドユーザー: アプリケーション内の人物またはアカウントです。ユーザーには、選択した外部 ID、DevBase が作成する内部 ID、任意の名前とメールアドレス、およびメタデータの JSON オブジェクトがあります。
• プロジェクト API キー: アプリケーションが1つのプロジェクトのエンドユーザーを読み取りまたは変更するために使用するシークレットです。

#サインインと権限

各リクエストで Authorization: Bearer <token> ヘッダーを送信します。

• 開発者は Delino のログイントークンを使用します。プロジェクトと API キーを管理できるのは、現在テナントの Owner または Admin であるユーザーだけです。ログイントークンを使用してエンドユーザーを読み取り、変更することもできます。
• アプリケーションはプロジェクト API キーを使用します。キーは dbk_ で始まります。READ_ONLY キーはユーザーを検索して一覧表示します。CRUD キーはユーザーの作成、更新、削除も行えます。キーでプロジェクトやキーを管理することはできず、そのキー自身のプロジェクトでのみ機能します。

エンドユーザーが DevBase にサインインすることはありません。エンドユーザーのレコードによって Delino へのアクセス権が付与されることもありません。

#クイックスタート

1. プロジェクトを作成します。 テナント ID と名前を指定して CreateProject を呼び出します。名前は大文字と小文字を区別せず、テナント内で一意である必要があります。
2. キーを発行します。 プロジェクト ID と権限を指定して IssueApiKey を呼び出します。レスポンスにシークレットが一度だけ含まれます。シークレットマネージャーに保存してください。
3. ユーザーを登録します。 キーを使用して CreateEndUser を呼び出します。返された id を独自のユーザーレコードと一緒に保存します。
4. ユーザーを検索します。 内部 ID では GetEndUser、外部 ID では LookupEndUser を使用します。
5. ユーザーを変更または削除します。 現在の version を指定して UpdateEndUser と DeleteEndUser を使用します。

すべてのプロシージャは devbase.v1.DevBaseService にあります。任意の Connect クライアント、または HTTP 経由のプレーン JSON を使用し、サーバー側コードまたはコマンドラインから DevBase を呼び出してください。ブラウザーから呼び出したり、プロジェクトキーをフロントエンドコードに含めたりしないでください。DevBase は自身のコンソール以外からのすべてのブラウザーオリジンを拒否します。DEVBASE_URL を DevBase API サーバーのベース URL に設定します。たとえば、ローカルサーバーの場合は http://127.0.0.1:46317 です。

# Create a project with your Delino login token.
curl --request POST "$DEVBASE_URL/devbase.v1.DevBaseService/CreateProject" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $DELINO_TOKEN" \
  --data '{"idempotencyKey":"3f1f6d1e-5a0a-4d7b-9a53-0c1d9f7a7d01","tenantId":"<tenant-id>","name":"My app"}'

# Issue a CRUD key for the project. The secret appears only in this response.
curl --request POST "$DEVBASE_URL/devbase.v1.DevBaseService/IssueApiKey" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $DELINO_TOKEN" \
  --data '{"idempotencyKey":"8c2b7a60-91a0-4a53-a9c3-6f7f0b2f1e02","projectId":"<project-id>","permission":"API_KEY_PERMISSION_CRUD"}'

# Register an end user with the project key.
curl --request POST "$DEVBASE_URL/devbase.v1.DevBaseService/CreateEndUser" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $DEVBASE_KEY" \
  --data '{"idempotencyKey":"d5f0c3a2-2b1e-4f59-8f0a-5b7c9e4d3a03","projectId":"<project-id>","externalId":"user-1001","email":"ada@example.com","metadata":{"plan":"pro"}}'

JSON では、フィールド名に lowerCamelCase、列挙値に完全名を使用し、version などの64ビット数値は文字列として表します。

#プロジェクト

• プロジェクト名は1～256バイトで、先頭または末尾に空白を含めることはできません。
• UpdateProject は名前を変更します。DeleteProject はプロジェクト、そのすべてのユーザー、およびすべてのキーを一度に削除します。
• 1つのテナントには最大100個のプロジェクトを作成できます。

#プロジェクト API キー

• 1つのプロジェクトには最大20個の有効なキーを設定できます。キーは、取り消されるか期限切れになるまで有効です。
• キーに有効期限が必要な場合は、発行時に expire_time を設定します。設定しなければ、キーが自動的に期限切れになることはありません。
• DevBase はシークレットのハッシュのみを保存します。シークレットを紛失した場合は、そのキーを取り消して新しいキーを発行してください。キーをローテーションするには、最初に新しいキーを発行してから古いキーを取り消します。
• IssueApiKey のレスポンスを失った場合は、同じ冪等性キーを使用してリクエストを繰り返します。繰り返したリクエストのレスポンスにはキー ID と権限が含まれますが、シークレットは含まれません。
• RevokeApiKey は直ちに反映されます。取り消されたキーまたは期限切れのキーを使用すると unauthenticated が返されます。

#エンドユーザー

• 同じ外部 ID を異なるプロジェクトに作成できます。1つのプロジェクトには最大1,000,000人のユーザーを登録できます。
• 作成は明示的に行います。DevBase には upsert がなく、メールアドレス、名前、メタデータによる検索もありません。
• UpdateEndUser は、external_id、name、email、metadata を指定した update_mask を使用します。マスクされた name または email に空の値を指定すると、その値がクリアされます。マスクされた metadata はオブジェクト全体を置き換え、空のオブジェクトを指定するとクリアされます。外部 ID はクリアできません。変更することはでき、その場合も内部 ID は変わりません。
• DeleteEndUser はユーザーを直ちに完全に削除します。その外部 ID はすぐに再利用できます。同じ ID を持つ次のユーザーには新しい内部 ID が割り当てられ、削除されたユーザーとの関連はありません。
• DevBase は削除について他のサービスに通知しません。ダウンストリームのデータは独自のアプリケーションで削除してください。

#一覧

ListProjects、ListApiKeys、ListEndUsers は、作成順で項目を返します。デフォルトのページサイズは50、最大値は100です。next_page_token が空になるまで、その値を使用して呼び出しを繰り返します。トークンは不透明な値として扱ってください。一覧に総件数はありません。ページを読み取っている間に項目を作成または削除すると、ページからそれらの項目が欠落したり、スキップされたりすることがあります。読み取りの全期間を通じて存在する項目は1回だけ表示されます。

#再試行と競合

• すべての変更には、A-Z、a-z、0-9、.、_、:、- からなる8～128文字の idempotency_key が必要です。UUID が適しています。
• 24時間以内に同じキーと同じ内容でリクエストを繰り返すと、最初の結果が返され、DevBase が再度変更を行うことはありません。レスポンスを失った場合の解決にこれを使用します。24時間が経過すると、そのキーは新しいリクエストとして扱われます。
• 同じキーを異なる内容で使用すると already_exists が返されます。各呼び出し元は独自のキーを持つため、別の呼び出し元が結果を参照したり取得したりすることはできません。
• 繰り返されたリクエストは、現在の権限に対して再度確認されます。最初の呼び出しから再試行までの間にアクセス権が失われることがあります。
• ユーザーを削除した後、そのユーザーの作成または更新を繰り返すと not_found が返され、DevBase がユーザーを再作成することはありません。削除の繰り返しは成功します。プロジェクトを削除すると、そのプロジェクトのキーは機能しなくなります。
• UpdateProject、UpdateEndUser、DeleteProject、DeleteEndUser には現在の version が必要です。先に他の誰かが項目を変更した場合は aborted が返されます。項目を再度読み取り、新しいバージョンで再試行してください。

#制限

ユーザーリクエストは、1つのプロジェクトのすべてのキーとログイントークンを合算してカウントされます。管理リクエストはテナント単位で合算してカウントされます。新しいキーを作成しても容量は増えません。制限を超えると resource_exhausted が返されます。レート制限の場合は、エラーと Retry-After ヘッダーに待機時間が示されます。オペレーターはこれらの制限を変更できます。これらはサービスを保護するためのものであり、速度を保証するものではありません。

#エラー

すべてのレスポンス、および DevBase 自身が返すすべてのエラーにはトレース ID があります。サポートを依頼する際には、その ID を含めてください。256 KiB を超えるリクエストは、それより前にトランスポートによって拒否され、resource_exhausted が返されますが、トレース ID はありません。代わりにリクエストサイズを小さくしてください。変更操作で unavailable が返された場合は、同じ冪等性キーを使用して同じリクエストを繰り返し、変更が適用されたかどうかを確認してください。

#テナントの状態

DevBase は無料です。プラン、残高、請求書によって利用が制限されることはありません。制限されるのは、オペレーターによるブロックとテナントの削除だけです。

• テナントがブロックされている間、または削除処理中である間は、プロジェクト API キーは機能しません。Owner と Admin は引き続きプロジェクトとキーを読み取り、キーを取り消し、ユーザーとプロジェクトを削除できます。何かを作成または変更したり、キーを発行したり、ユーザーを読み取ったりすることはできません。
• DevBase がテナントの状態を確認できない場合、推測は行わず、unavailable または permission_denied でリクエストを拒否します。
• テナントが完全に削除されると、DevBase はそのプロジェクト、ユーザー、キーを自動的に削除します。

#DevBase が行わないこと

DevBase は、ユーザーをサインインさせたり、ユーザー用の Delino アカウントを作成したり、ユーザーに代わって操作したりしません。プロジェクト間でのユーザー共有、テナント間でのプロジェクト移動、データのインポートまたはエクスポート、ユーザー検索も行いません。バックアップが存在する場合、それは DevBase がアクティブデータに適用する即時削除の対象外です。