## 概要 [API](/ja/manual/api)と[拡張SQL](/ja/manual/extended-sql)を組み合わせてデータベースから直接データを取得したり更新したりすることができます。 ## 注意事項 1. 誤って使用するとプリザンターが利用できなくなったり、データが壊れたりする可能性がありますので、十分なテストを行った上でご利用ください。 1. APIキーやセッションによるログイン確認は行いますが、テーブルへの権限チェックなどが行われないため、SQLの中で実施する必要があります。 1. [レコード取得API](/ja/manual/api-record-get)と異なり、取得件数の上限はありません。そのため取得内容・条件によっては処理時間が非常に長くなる可能性がありますので、十分なテストを行った上でご利用ください。 ## 制限事項 1. 拡張SQLのJSONファイルやSQLファイルを更新した後は「アプリケーションを再起動」するまで反映しません。 1. セキュリティ上の理由により拡張SQLはWeb画面から設定できません。 ## 事前準備 APIの操作を行う前に[APIキーの作成](/manual/api-key)を実施してください。 .jsonファイルにて以下の2項目は必須項目となります。 |パラメータ名|設定例|説明| |:--|:--|:--| |Name|Sample|APIから実行させる際の名前を設定します。| |Api|true|trueの場合APIからの実行を許可します。| CommandTextに直接SQL文を記載できますが、SQL文が長文になる場合など、ファイルを分けることが可能です。 その場合のファイル名は以下の画像のように、.jsonファイルと同名.sqlとしてください。 例) APItoSQL.json　←定義ファイル APItoSQL.json.sql　←SQL文  ## URL 下記のURLを使用します。 HTTPメソッドはPOSTです。 http://{ServerName}/api/extended/sql "http://{ServerName}" の部分は、環境に合わせて編集してください。 ## リクエスト 下記例のようにParamsに入れたパラメータは@RefIDのように拡張SQLに渡すパラメータとして使用することができます。 標準で用意されている@_Uなどのパラメータも使用できます。 ```json { "ApiVersion": 1.1, "ApiKey": "XXXXXXXXXX...", "Name": "Sample", "Params": { "RefID": 1 } } ``` ## JSONファイル APItoSQL.json ```json { "Name": "Sample", "Api": true } ``` ## SQL文(外部ファイル) APItoSQL.json.sql ```sql SELECT [ReferenceId] ,[DeptId] ,[GroupId] ,[UserId] ,[Ver] ,[PermissionType] FROM [Implem.Pleasanter].[dbo].[Permissions] WHERE [ReferenceId]=@RefID ``` ## レスポンス テーブル内にはレコードの配列があり、レコード内はKey, ValueのHashでカラム名と値が入ってきます。 ```json { "StatusCode": 200, "Response": { "Data": { "Table": [ { "ReferenceId": 1, "DeptId": 0, "GroupId": 0, "UserId": 1, "Ver": 1, "PermissionType": 511 }, { "ReferenceId": 1, "DeptId": 0, "GroupId": 0, "UserId": 9, "Ver": 1, "PermissionType": 31 }, { "ReferenceId": 1, "DeptId": 0, "GroupId": 0, "UserId": 10, "Ver": 1, "PermissionType": 31 }, { "ReferenceId": 1, "DeptId": 0, "GroupId": 1, "UserId": 0, "Ver": 1, "PermissionType": 511 } ] } } } ``` 複数のテーブルから値を取得した場合は以下のようなレスポンスとなります。 Response.Data.Table （1つめのテーブル） Response.Data.Table1 （2つめのテーブル） Response.Data.Table2 （3つめのテーブル） ## ユーザを指定して実行する 操作対象のオブジェクトの所有者がImplem.Pleasanter_Ownerである場合、以下のようなエラーが発生します。 例）PostgreSQLでItemsテーブルへのInsertをUser権限で実行した場合 「"PostgresException: 42501: permission denied for sequence Items_ReferenceId_seq"」 これは、シーケンスオブジェクトの所有者がImplem.Pleasanter_Ownerであるのに対して、実行者がImplem.Pleasanter_Userであるためです。 APIから拡張SQLを実行する際に以下のように指定すると、Owner権限で実行することができます。 ## JSONファイル APItoSQL.json ```json { "Name": "Sample", "Api": true, "DbUser": "Owner" } ``` ## 関連情報 <div id="ManualList"><ul><li><a href="/ja/manual/api">開発者向け機能：API</a><span>2023/08/16 up</span></li> <li><a href="/ja/manual/api-record-get">開発者向け機能：API：テーブル操作：単一レコード取得</a><span>2023/08/17 up</span></li> <li><a href="/ja/manual/api-record-get-multi">開発者向け機能：API：テーブル操作：複数レコード取得</a><span>2023/12/14 up</span></li></ul></article> <ul><li><a href="/ja/manual/extended-sql">開発者向け機能：拡張機能：拡張SQL</a><span>2024/09/13 up</span></li></ul></article> <ul><li><a href="/ja/manual/faq-api-paging">FAQ：API で 200 レコードを超えるデータを取得したい</a><span>2024/04/29 up</span></li> <li><a href="/ja/manual/faq-api">FAQ：API実行でエラーになる</a><span>2024/04/29 up</span></li> <li><a href="/ja/manual/faq-json-format">FAQ：変更後の設定ファイルやAPIリクエスト(JSON形式)が正しく認識されない場合の確認事項</a><span>2024/04/29 up</span></li></ul></article></div><input id="SearchTextHidden" type="hidden" value="" />