クライアントAPI

PowerPortalsProは、どのシングルページアプリケーションでも呼び出せるJSONオーバーHTTPサーフェスを /api/* で公開しています。Blazor WebAssemblyクライアントはこれをバックで IPowerPortalsProService や IAuthServiceに使いますが、同じエンドポイントはReact、Vue、またはバニラJSフロントエンドでもサーバーと並行して(あるいはクロスオリジン)して同様に利用できます。このページは完全な参考資料です:すべてのクライアントが呼び出す可能なエンドポイントと、サンプル要求と応答を含んでいます。

これは誰宛てですか
Blazorアプリを構築し、 IPowerPortalsProServiceを通じてフレームワークを利用する場合、これらのエンドポイントを直接呼び出す必要はありません。クライアント実装が代わりに呼び出します。このページでは、非BlazorのSPAを書くチームやカスタムHTTPクライアントを同じサーバー上で配線するチームのための表面を記録しています。

エンドポイントの有効化

UsePowerPortalsProWebServer データエンドポイント(テーブルCRUD、FetchXML、メタデータ、ファイル、ローカライズ、管理者)を配線します。 MapAuthEndpoints<TUser> SPA向きの認証サーフェスを配線します。ホストがSPAからクッキー認証を必要とする場合は明示的に呼び出してください。

両方の通話は機能を使わないときはノーオペス(無操作)なので、ホストがどのインタラクティビティモードを使っていても Program.cs に一度だけ配線してください。

ルートタイプ — 単一の真実の情報源

PowerPortalsPro.Web.Common.Routes すべての端点パスを強型付きプロパティとして公開します。インボックスクライアントもC#ベースの外部SPAもこれらの定数を参照すべきであり、手書き文字列ではなく、サーバー側のリネームはランタイム404ではなくコンパイルエラーとして現れます。JavaScriptやTypeScriptクライアントはもちろんパスをインライン化する必要がありますが、C#側 Routes パスの標準的な参照として使われています。

Routes.Api データおよび管理エンドポイントをカバーします。 Routes.Api.Auth はサインイン/サインアップ、 Routes.Api.Auth.Manage をカバーしています。サインインしたユーザーのアカウント管理業務をカバーします。

認証モデル — トークンではなくクッキー

認証はブラウザクッキーベースです。JWT発行のステップはありません。SPAが/api/auth/loginを呼び出し、サーバーは応答に対して.AspNetCore.Identity.Applicationクッキーを設定し、ブラウザはその後のすべてのリクエスト(/api/table/*でのデータ呼び出しを含む)にそれをアタッチします。JavaScriptからは、すべての通話(またはaxios.defaults.withCredentials = true)でfetch(..., { credentials: 'include' })を意味します。JavaScriptがなければクッキーはドロップされ、サーバーは401を返します。以下のすべての例がそれを含めています。

クロスオリジンSPA
SPAとサーバーが異なる発信元にある場合、サーバーは Access-Control-Allow-Origin: <spa-origin> ( *ではなく)と Access-Control-Allow-Credentials: trueを送信し、SPAは credentials: 'include'を使わなければなりません。同じソースホスティング(APIと同じサイトからSPAを提供する)はこの問題を完全に回避します。

記録の形状

行を読み書きするすべてのデータエンドポイントは同じエンベロープ TableRecord 交換します。 properties は、列論理名のマップ→型付き値オブジェクトのマップであり、その $type 識別子が列の種類を識別します。 permissions ビットフラグマスク(Read 1、Create 2、Write 4、Delete 8、Append 16、AppendTo 32)で、現在のユーザーが行で何をするかを記述します。書き込み時は、変更する列だけを送ればいいです。

$type値はDataverse属性の種類を反映しています:0 ブール、2 DateTime、3 Decimal、4 Double、5 Integer、6 Lookup、8 Money、11 Choice、14 String、15 UniqueIdentifier、40 MultiSelectChoice、41 File、42 画像。ルックアップはname+tableNameを加え、数値、マネー、日付の値はDataverse形式のformattedValueを持ちます。

エラー応答

失敗した通話はRFC 9457 application/problem+jsonを返します。インボックスクライアントの実装は、問題の詳細から元のCLR例外タイプをリハイドレートするため、サーバー側はクライアント側で同じ例外として表面をスローします。non-.NET SPAでは、 type / title / detail / status フィールドが標準ハンドルです。

エンドポイント参照

以下の各エンドポイントは、メソッドとパス、その役割、サンプルリクエスト(ブラウザ fetch コールとしての)、およびサンプルレスポンスを示しています。 {braces} のパスセグメントはプレースホルダーです。特に記載がない限り、2xxの応答が成功例であり、失敗は problem+jsonとして返ってきます。

記録とCRUD

単一レコードの作成、読み取り、更新、削除に加え、任意のFetchXMLクエリやトランザクションバッチも可能です。 UsePowerPortalsProWebServerに裏付けられ、すべての読み書きは消費者の ITablePermissionHandler / ITableRecordPermissionHandler インターセプターおよび登録された IFetchXmlBuilderInterceptor を適用します。

`POST /api/table/{tableLogicalName}`

名前付きテーブルに新しい行を作成します。設定する列を載せた TableRecord を送信します。応答は新しいレコードのIDを返します。

要望

反応

`GET /api/table/{tableLogicalName}/{recordId}`

IDで1行読み取る。オプションの ?columns= クエリパラメータ(カンマ区切られた論理名)は射影を絞り込みます — テーブルのデフォルトカラムセットを取得するために省略してください。

要望

反応

`PATCH /api/table/{tableLogicalName}/{recordId}`

既存の行を更新します。 properties にある列だけが書き込まれているので、変更した値だけを送信してください。

要望

反応

`DELETE /api/table/{tableLogicalName}/{recordId}`

IDで行を削除します。

要望

反応

`GET /api/retrieveMultiple?fetchXml=…`

任意のFetchXMLクエリを実行し、対応する行とページング情報を返します。FetchXMLを fetchXml クエリ文字列にC#からエンコードしてください。 Routes.Api.GetRetrieveMultipleRoute(fetchXml) これを代わりに行います。

要望

反応

`POST /api/executeMultiple?returnResponses=true|false`

単一のデータベーストランザクションで異種リクエスト(作成/更新/削除/アソシエイト/離脱)を一括実行し、いずれかが失敗するとバッチ全体がロールバックされます。本体は$typeによって区別されたOrganizationRequestオブジェクトのJSON配列です。リクエストごとのレスポンスリスト作成をスキップするには?returnResponses=falseパスしてください。

要望

反応

グリッドとチャート

サーバー構成クエリエンドポイント。クライアントにFetchXMLをビルドさせる代わりに、ビューID(または自分のFetchXML)と検索・ソート・ページングを渡し、サーバーが列を解決し、権限を適用しクエリを実行します。これはMainGridやチャートコンポーネントが使う単一真実の経路と同じです。

`POST /api/grids/data`

グリッドデータのページを読み込みます。 viewId またはご自身のご fetchXml、さらにオプションで searchText、 sorts、ページング、カラムフィルターも用意してください。レスポンスは行、解決された列の定義、呼び出し元のテーブル権限マスクを伝えます。

要望

反応

`POST /api/charts/data`

チャート作成コンポーネント向けに集約されたチャートデータを読み込みます。集計設定、 viewId、生の fetchXmlに加え、ラベル/値/系列の列マッピングを受け付けます。Chart.jsスタイルのラベルとデータセットを返します。

要望

反応

メタデータと権限

テーブルやビューメタデータ、現在のユーザーの権限マスク、組織全体の設定の読み取り専用ルックアップ。すべてサーバーサイドでキャッシュされているため、繰り返し通話は安価です。

`GET /api/tableMetadata/{tableLogicalName}`

テーブルのメタデータ、すなわち型、ラベル、制約付きカラム、プライマリid/名前/画像カラム、リレーションシップを返します。

要望

反応

`GET /api/permissions/table/{tableLogicalName}`

現在のユーザーのテーブルの統合 TableSecurityPermission マスクを単一の整数として返します(ビットフラグ:Read 1, Create 2, write 4, Delete 8, Append 16, AppendTo 32)。

要望

反応

`GET /api/viewMetadata/{viewId}`

保存されたビューのメタデータをGUID(FetchXML、レイアウトカラム、ビューフラグ)で返します。このルートにはGUIDが必要で、以下の全ビュールートと区別されています。

要望

反応

`GET /api/viewMetadata/{tableLogicalName}`

テーブルの保存済みすべてのビューを返します。by-idルートと共通の /api/viewMetadata/ プレフィックス — 非GUIDセグメント(テーブルの論理名)がここに着きます。

要望

反応

`GET /api/organizationSettings`

Dataverseの組織レコードから得た組織全体の設定を返します:デフォルトの通貨、ブロックされたファイル拡張子リスト、最大アップロードサイズ(バイト単位)。

要望

反応

ファイル

ファイルと画像の列の内容を読みます。バイナリペイロードはJSON内でbase64エンコードで返されます。 includeData フラグは、バイトを転送せずにメタデータのみを取得することを可能にします(例:ダウンロードリストのレンダリング)。

`GET /api/files/{tableLogicalName}/{recordId}/{columnName}?includeData=…`

1つのレコードでファイル/画像列のメタデータを返します。 ?includeData=true ではbase64の内容が埋め込まれますが、 false では名前とサイズのみが戻ってきます。

要望

反応

`POST /api/files/{tableLogicalName}/{columnName}/batch?includeData=…`

同じテーブル/カラムの多くのレコードのメタデータ(およびオプションで内容)を一度の往復で取得します — 本体はレコードGUIDのJSON配列です。FileGridのダウンロード選択で使われ、クライアントがN回の個別呼び出しを発生させないようにします。

要望

反応

`POST /api/files/createFileArchive`

サーバー側でレコードセットのファイルカラム値をZip化します。デフォルトで生の application/zip ストリームを返すか、 responseFormat: 1 の場合はbase64アーカイブを含むJSONエンベロープを返します。POST(GETではなく)で、大きなIDリストがURL長の制限に耐えないようにします。

要望

反応

局在束

非Blazorのフロントエンド向けのローカライズされた文字列。 /api/localizedStrings ルートは文化のツリー全体を返します。 /localizations/* ルートはサムプリント付きで不変キャッシュされたバンドル(デフォルト、テーブルごと、ビューごと)を提供し、効率的な増分ロードを実現します。これらは公開されており、認証クッキーを必要としません。

`GET /api/localizedStrings/{culture}`

文化のローカライズされた文字列ツリー全体をネストオブジェクトとして返します — フレームワーク文字列、アプリのオーバーライド、テーブルラベル、選択ラベルなどです。

要望

反応

`GET /localizations/version`

ローカライゼーションマニフェストを返します — サポートされているローカリストのリストだけです。キャッシュなしで提供されているので、次のページロード時に新しいリリースが検出されます。公衆。

要望

反応

`GET /localizations/{locale}/thumbprints`

1つのローカ(デフォルトのバンドルと読み込まれたすべてのテーブルとビュー)のコンテンツのサムプリントを返します。クライアントはこれらを取得し、サムプリントが変わったバンドルのみを要求します。公衆。

要望

反応

`GET /localizations/default/{filename}` · `/tables/{tableName}/{filename}` · `/views/{viewId}/{filename}`

3つのバンドルファミリーは、デフォルト(クロスカッティング文字列)、per-table(テーブルの文字列とその列が参照するグローバル選択)、およびper-viewです。ファイル名は {locale}.{thumbprint}.json されており、それぞれ public, immutable, max-age=31536000に配信されるため、安定したサムプリントはキャッシュヒットが保証されます。公衆。

要望

反応

文化

文化クッキーを書き込むことでブラウザのアクティブな文化を切り替えます。

`GET /Culture/{culture}?redirectUri=…`

文化クッキーと302リダイレクトを redirectUriに設定します。取得するのではなく、ページ全体読み込みでナビゲートして、 Set-Cookie とリダイレクトが有効になります。公衆。

要望

反応

管理者 — キャッシュ管理

サーバーキャッシュの検査と無効化。3つのエンドポイントはすべて [Authorize(Roles = "SystemAdmin")] でゲートされており、サインインした管理者のみが呼びかけることができます。

`GET /api/caches`

登録されたすべてのサーバーサイドキャッシュの名前を一覧にします。SystemAdminの役割が必要です。

要望

反応

`POST /api/caches/clear`

すべてのサーバー側キャッシュをクリアし、キャッシュごとに成功したかどうか、そして所要時間などの結果を返します。SystemAdminの役割が必要です。

要望

反応

`POST /api/caches/{cacheName}/clear`

名前はリストエンドポイントから来る単一の名前付きキャッシュをクリアします。404の名前のキャッシュが登録されていなければ返されます。SystemAdminの役割が必要です。

要望

反応

認証

サインイン、サインアップ、アカウントライフサイクル、 MapAuthEndpoints<TUser>によるサポート。クッキーベース:サインインが成功すると ASP.NET Core Identityアプリケーションクッキーが設定され、その後の呼び出しごとにそれを返して認証します。ほとんどのシステムは、ステータスコードを通じて結果を伝えるのではなく、HTTP 200で result 列挙を返します。

`POST /api/auth/login`

メール+パスワードでサインインします。 result 列挙は、成功、必須の第二要素、悪い資格情報、未確認のメール、ロックアウトを区別します。成功すると、レスポンスに対して認証クッキーが設定されます。

要望

反応

`POST /api/auth/login/2fa`

認証ツール(またはリカバリー)コードを提出することで、返 RequiresTwoFactor されたサインインを完了します。 rememberMachine 、このブラウザでの今後のサインイン時に2つ目の要素をスキップするように、信頼されたブラウザクッキーを設定します。

要望

反応

`POST /api/auth/logout`

認証クッキーをクリアし、セッションを終了します。

要望

反応

`POST /api/auth/register`

新しいローカルアカウントを作成します。設定によっては、確認メール送信、即時サインイン、または既存のメールとの競合のいずれかが発生します。弱いパスワードやその他の検証失敗は400 problem+jsonと表示されます。

要望

反応

`POST /api/auth/forgot-password`

リセットリンクをメールで送ることでパスワードリセットを開始します。必ず200を返すが、そのアドレスの存在は確認せず、登録済みメールの調査には使えません。

要望

反応

`POST /api/auth/reset-password`

メールのトークンと新しいパスワードを使ってリセットを完了します。 result 成功、無効または期限切れトークン、却下されたパスワード(検証メッセージが errorsにある)を区別します。

要望

反応

`POST /api/auth/confirm-email`

確認リンクからユーザーIDとトークンを使って新たに登録されたメールを確認します。

要望

反応

`POST /api/auth/resend-email-confirmation`

確認メールのリンクを再送信します。forgot-passwordのように、登録済みアドレスの漏洩を避けるために、必ず200を返します。

要望

反応

`GET /api/auth/options`

サインイン設定を1回の匿名通話で返します: localAccountsEnabled (ポータルがローカルのユーザー名/パスワードアカウントを受け入れているか否)と、サインインボタン用の設定済み外部(OAuth)プロバイダー(スキーム名と表示名)を含みます。

要望

反応

`GET /api/auth/external-login?provider=…&returnUrl=…`

プロバイダーのOAuthフローをスタートさせます。プロバイダーに302チャレンジを返すので、ブラウザでそれにアクセスし(取得しないでください)、SPAは window.location.hrefを設定するべきです。

要望

反応

`GET /api/auth/external-login/pending`

OAuthコールバック後、機内外部ログインのスナップショットを抽出します:プロバイダー名、アイデンティティの主張、そしてメールが複数のポータルIDと一致した場合は、選択可能な候補リストです。保留中のログインがないと204ページを返します。

要望

反応

`POST /api/auth/external-login/confirm`

新しいアカウントの初回外部サインインを、アソシエイトにメールアドレスを確認することで完成します。サインイン、確認メール、保留なし、失敗に解決します。

要望

反応

`POST /api/auth/external-login/select`

複数のポータルIDと一致した際、どちらか(ContactまたはSystemUser)でサインインすることで外部サインインを完了します。

要望

反応

`GET /api/auth/me`

現在の校長のスナップショット — ID、名前、メールアドレス、役割、バックアップテーブル(contact 対 systemuser)、さらに任意の兄弟姉妹の識別名。クッキーが存在しない場合、401ではなく匿名の形状(isAuthenticated: false)を返すため、SPAはステータスコードで分岐せずに最初のペイントで呼び出せます。

要望

反応

`POST /api/auth/switch-identity`

現在のクッキーをユーザーの別の兄弟身分(Contact↔SystemUserペアリングは /api/auth/meに出現)に交換します。JSONの本体は空のオブジェクトです。

要望

反応

アカウント管理

サインインしたユーザーのセルフサービス操作は、プロフィール、パスワード、メール、二要素認証、リンクされた外部ログイン、個人情報など、 /api/auth/manage/* で行われます。すべて認証セッションが必要で、フレームワークのクラシックな /Account/Manage Razorページをミラーリングします。

`GET /api/auth/manage/profile`

Dataverseの連絡先から読んだユーザーのプロフィール(名前、モバイル端末、メールアドレス)と、Identityステータスフラグ(メール確認済み、パスワード設定、2段階認証有効、読み取り専用)を返します。

要望

反応

`POST /api/auth/manage/profile`

リンク先の連絡先で氏名・名字と携帯電話番号を更新します。成功すると200を返す。SystemUserバックアップのIDは読み取り専用で、403を取得します。

要望

反応

`POST /api/auth/manage/password/set`

ローカルパスワードを持たないアカウント(例:外部ログイン専用アカウント)に追加します。もし何かあれば、 errorsに確認メッセージが返ってきます。

要望

反応

`POST /api/auth/manage/password/change`

ローカルパスワードを変更する;現在のパスワードが必要です。 result 成功、間違った現在のパスワード、拒否された新しいパスワードを区別します。

要望

反応

`POST /api/auth/manage/email/change`

新しい住所に確認リンクを送ることでメール変更を開始します。この変更は、そのリンクをたどった場合にのみ有効です。

要望

反応

`POST /api/auth/manage/email/send-confirmation`

ユーザーの現在のメールアドレスの確認リンクを再送信します。 sent メールがすでに確認されている場合は誤りです。

要望

反応

`GET /api/auth/manage/2fa`

2FAの状態を返します — 認証ソフトが登録されているか、2FAが有効か、このブラウザが記憶されているか、そして残っている回復コードの数です。

要望

反応

`GET /api/auth/manage/authenticator/setup`

共有キーとQRコード登録画面用の otpauth:// URIを返します。Verifyエンドポイントとペアリングして2段階認証の有効化を完成させます。

要望

反応

`POST /api/auth/manage/authenticator/verify`

認証アプリからコードを検証し、2段階認証を有効にします。最初の登録時には、応答は初期の復旧コードのセットも返します。

要望

反応

`POST /api/auth/manage/authenticator/reset`

認証キーを回転させます。これにより2段階認証も無効化され、ユーザーは再登録しなければなりません。

要望

反応

`POST /api/auth/manage/2fa/disable`

アカウントの2段階認証をオフにします。

要望

反応

`POST /api/auth/manage/2fa/recovery-codes/generate`

既存のセットを置き換えてリカバリコードを再生成し、新しいコードを返します。

要望

反応

`POST /api/auth/manage/2fa/forget-browser`

このブラウザの信頼デバイスクッキーがクリアされるため、次のサインイン時に再び2段階認証が必要になります。

要望

反応

`GET /api/auth/manage/external-logins`

現在アカウントにリンクされている外部ログイン情報が一覧です。

要望

反応

`GET /api/auth/manage/login-info`

ユーザーのサインインパスの統合ビュー(リンクされた外部ログインとローカルパスワードの設定の有無)を用いて、ログイン解除によってユーザーがロックアウトされるかどうかを判断します。

要望

反応

`GET /api/auth/manage/external-logins/link?provider=…`

サインイン済みアカウントに追加のプロバイダーをリンクするOAuthフローを開始します。302チャレンジを返すので、取ってくるのではなくそこへ向かうべきです。

要望

反応

`GET /api/auth/manage/external-logins/link/callback`

リンクフローのOAuthコールバック。プロバイダーはブラウザをここにリダイレクトします。サーバーは、最初に提供された returnUrl にログインと302-リダイレクトを添付します。これを直接呼ぶわけじゃない。

要望

反応

`POST /api/auth/manage/external-logins/remove`

プロバイダー+プロバイダーキーで外部ログイン1つをアンリンクします。

要望

反応

`GET /api/auth/manage/personal-data`

ユーザーの個人データ—すべての [PersonalData] 財産とリンクされた外部ログイン—をエクスポートし、GDPRスタイルのダウンロード用にします。

要望

反応

`POST /api/auth/manage/personal-data/delete`

ユーザーのアカウントを永久に削除し、サインアウトします。アカウントに現在のパスワードがある場合は、そのパスワードが必要です。外部専用アカウントにはパス null 。 result 成功、誤ったパスワード、パスワードが必要で提供されていない場合を区別します。

要望

反応

クライアントAPI

エンドポイントの有効化

ルートタイプ — 単一の真実の情報源

認証モデル — トークンではなくクッキー

記録の形状

エラー応答

エンドポイント参照

記録とCRUD

POST /api/table/{tableLogicalName}

GET /api/table/{tableLogicalName}/{recordId}

PATCH /api/table/{tableLogicalName}/{recordId}

DELETE /api/table/{tableLogicalName}/{recordId}

GET /api/retrieveMultiple?fetchXml=…

POST /api/executeMultiple?returnResponses=true|false

グリッドとチャート

POST /api/grids/data

POST /api/charts/data

メタデータと権限

GET /api/tableMetadata/{tableLogicalName}

GET /api/permissions/table/{tableLogicalName}

GET /api/viewMetadata/{viewId}

GET /api/viewMetadata/{tableLogicalName}

GET /api/organizationSettings

ファイル

GET /api/files/{tableLogicalName}/{recordId}/{columnName}?includeData=…

POST /api/files/{tableLogicalName}/{columnName}/batch?includeData=…

POST /api/files/createFileArchive

局在束

GET /api/localizedStrings/{culture}

GET /localizations/version

GET /localizations/{locale}/thumbprints

GET /localizations/default/{filename} · /tables/{tableName}/{filename} · /views/{viewId}/{filename}

文化

GET /Culture/{culture}?redirectUri=…

管理者 — キャッシュ管理

GET /api/caches

POST /api/caches/clear

POST /api/caches/{cacheName}/clear

認証

POST /api/auth/login

POST /api/auth/login/2fa

POST /api/auth/logout

POST /api/auth/register

POST /api/auth/forgot-password

POST /api/auth/reset-password

POST /api/auth/confirm-email

POST /api/auth/resend-email-confirmation

GET /api/auth/options

GET /api/auth/external-login?provider=…&returnUrl=…

GET /api/auth/external-login/pending

POST /api/auth/external-login/confirm

POST /api/auth/external-login/select

GET /api/auth/me

POST /api/auth/switch-identity