Open API
概要
SERVICEME Open API 呼び出しの基本フロー：
第一ステップ、認証セクションで提供されているインターフェースを使用して認証を行い、アクセストークンを取得する
認証には2種類あり、一つはユーザー認証、もう一つはクライアント認証です。
- ユーザー認証：個人アカウントの身 分に基づいて認証を行う方法。
- クライアント認証：SERVICEMEが発行するクライアントコードとシークレットを使用して認証を行う方法。
第二ステップ、アクセストークンを持って対応するAPIを呼び出す
認証方法
ユーザーAAD認証
この方法はユーザー認証の一種で、AADのアクセストークンを認証の根拠として使用します。
-
AADアクセストークンの取得方法：
AADとReactの統合ドキュメント：前往->
AADと.Netの統合ドキュメント：前往->
AADとJavaの統合ドキュメント：前往->
-
インターフェースアドレス：
/openapi/auth/user/aad -
リクエスト方法：
post -
リクエストボディ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| token | はい | string | ユーザーAADアクセストークン（接続側が提供） |
- インターフェースリクエスト例：
curl --location 'https://localhost/openapi/auth/user/aad' \
--header 'Content-Type: application/json' \
--data '{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlhSdmtvOFA3QTNVYVdTblU3Yk05blQwTWpoQSJ9.eyJhdWQiOiIzZTEwNjVhYS1jZWYxLTRiYTgtOWRiOS1kMWQ1Y2UzMGYyZDgiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNDRjMjRmNDItZDQ5Yi00MT......"
}'
- レスポンスボディ：
| パラメータ名 | サブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|
| data | object | レスポンスデータ | |
| access_token | string | SERVICEMEシステムのアクセストークン | |
| expires_in | number | 有効期限（分単位） | |
| success | boolean | 成功かどうか | |
| msg | string | successがfalseの場合、エラーメッセージが含まれる |
- レスポンス例：
{
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0V4dGVybmFsIjpmYWxzZSwidXNlcklkIjoiNDAzMDUwMjEwMTEyODgzOTE2OCIsImFjY291bnQiOiJlY210cmlhbEBzZXJ2aWNlbWUub25taWNyb3NvZ......",
"expires_in": 1440
},
"success": true,
"msg": ""
}
クライアントとユーザーアカウント認証
この認証方法は、クライアント認証とユーザーアカウント認証を組み合わせた方法です。ユーザーアカウントで認証を行い、同時にクライアント証明書（クライアントコードとシークレット）を使用してインターフェース呼び出しの安全性を確保します。このインターフェースを呼び出す際には署名検証が必要です。
- クライアントとシークレットの取得方法：
システム管理者に連絡してください。管理者は以下のアドレスを通じてクライアント証明書を作成し、割り当てます:
https://xxx/#/super-admin/client-management
-
インターフェースアドレス：
/openapi/auth/client_with_account -
リクエスト方法：
post -
リクエストボディ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| client | はい | string | クライアントコード（SERVICEME提供） |
| account | はい | string | ユーザーアカウント（接続側が提供） |
| timestamp | はい | number | タイムスタンプ（13桁の数字、ミリ秒単位、例：1711537596897） |
| nonce | はい | string | 6桁のランダム数（数字または文字の組み合わせ） |
| signature | はい | string | 署名、5分以内に有効（署名形式：コロンで連結後にMD5 client:{client}secret:{secret}account:{account}timestamp:{timestamp}nonce:{nonce} で得られるMD5 32桁の値を小文字に変換） |
-
javascript 署名例：
新しいhtmlファイルを作成し、以下の内容を貼り付けてブラウザで開いてください
<html>
<head>
<style>
.box {
width: 100%;
height: 100%;
padding: 50px 50px;
}
.row {
display: flex;
height: 50px;
width: 100%;
}
.col1 {
flex: 1;
}
.col2 {
flex: 3;
}
</style>
</head>
<body>
<div class="box">
<div class="row">
<div class="col1">client:</div>
<div class="col2" id="client"></div>
</div>
<div class="row">
<div class="col1">secret:</div>
<div class="col2" id="secret"></div>
</div>
<div class="row">
<div class="col1">account:</div>
<div class="col2" id="account"></div>
</div>
<div class="row">
<div class="col1">timestamp:</div>
<div class="col2" id="timestamp"></div>
</div>
<div class="row">
<div class="col1">nonce:</div>
<div class="col2" id="nonce"></div>
</div>
<div class="row">
<div class="col1">signature:</div>
<div class="col2" id="signature"></div>
</div>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/crypto-js.min.js"></script>
<script>
const client = "openapi"
const secret = "DzYwyICrKbUCEseYthCK0PfSfX7NPEuV"
const account = "test@serviceme.com"
const timestamp = +new Date()
const nonce = "123abc"
const message = `client:${client}secret:${secret}account:${account}timestamp:${timestamp}nonce:${nonce}` // 署名明文
const md5Hash = CryptoJS.MD5(message).toString().toLowerCase(); // MD5 32桁小文字
console.log(`署名明文：${message}`)
console.log(`署名結果：${md5Hash}`)
document.getElementById('client').innerText = client;
document.getElementById('secret').innerText = secret;
document.getElementById('account').innerText = account;
document.getElementById('timestamp').innerText = timestamp;
document.getElementById('nonce').innerText = nonce;
document.getElementById('signature').innerText = md5Hash;
</script>
</body>
</html> -
インターフェースリクエスト例：
curl --location 'https://localhost/openapi/auth/client_with_account' \
--header 'Content-Type: application/json' \
--data '{
"client": "openapi",
"account": "test@serviceme.com",
"timestamp": 1711537596456,
"nonce": "123abc",
"signature": "182be0c5cdcd5072bb1864cdee4d3d6e"
}'
- レスポンスボディ
| パラメータ名 | サブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|
| data | object | レスポンスデータ | |
| access_token | string | SERVICEMEシステムのアクセストークン | |
| expires_in | number | 有効期限（分単位） | |
| success | boolean | 成功かどうか | |
| msg | string | successがfalseの場合、エラーメッセージが含まれる |
- インターフェースレスポンス例：
{
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0V4dGVybmFsIjpmYWxzZSwidXNlcklkIjoiNDAzMDUwMjEwMTEyODgzOTE2OCIsImFjY291bnQiOiJlY210cmlhbEBzZXJ2ub25ta......",
"expires_in": 1440
},
"success": true,
"msg": ""
}
チャット
Copilotにメッセージを送信
-
インターフェースアドレス：
/openapi/chat/expert -
リクエスト方法：
post -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| Authorization | はい | string | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- リクエストボディ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| expertCode | はい | string | SERVICEMEシステムのCopilotコード（SERVICEMEシステム参照） |
| content | はい | string | 質問内容 |
| sessionId | いいえ | string | セッションID、チャットコンテキストを表し、nullを渡すと新しいセッションが開 始され、新しいセッションIDがインターフェースレスポンスで返されます。2回目以降の質問には前回のセッションIDを持って続けます。 |
| stream | いいえ | boolean | ストリーミングを有効にするかどうか（true：有効；false：無効）、デフォルトは無効 |
| includeThought | いいえ | boolean | レスポンス内容に思考を含めるかどうか（true：含める；false：含めない） |
**質問コードの取得方法？**以下の図を参照してください：
- リクエスト例：
curl --location 'https://localhost/vee/openapi/chat/expert' \
--header 'Authorization: openapi {access_token}' \
--header 'Content-Type: application/json' \
--data '{
"expertCode": "CHATES",
"content": "残業申請",
"sessionId": null,
"stream": false,
"includeThought": true
}'
- レスポンスボディ：
| パラメータ | サブパラメータ | サブサブパラメータ | サブサブサブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|---|---|
| data | object | レスポンスデータ | |||
| chatRecordId | string | チャット記録ID | |||
| sessionId | string | セッションID | |||
| content | string | テキスト形式の回答情報 | |||
| medias | object | メディア形式の回答情報配列（画像やファイルなど） | |||
| type | string | image：画像；file：ファイル | |||
| name | string | 名 前 | |||
| suggestionQuestions | array string | 推奨質問 | |||
| thoughts | array | 思考 | |||
| thought | string | 思考内容 | |||
| pluginName | string | プラグイン名 | |||
| elapsedTime | object | プラグインの経過時間情報 | |||
| model | float | モデルの経過時間 | |||
| action | float | アクションの経過時間 | |||
| total | float | 総経過時間 | |||
| state | string | 状態（success：成功） | |||
| finish_reason | string | 回答が終了したかどうか、値がstopの場合は終了、回答中はnull | |||
| success | boolean | 成功かどうか | |||
| msg | string | successがfalseの場合、エラーメッセージが含まれる |
- 非ストリーミングレスポンス例：
{
"data": {
"chatRecordId": "4299234148041625600",
"sessionId": "4292755814873047040",
"content": "チームリーダーが作業タスクを発行し、完了の期限と検収基準を明確にします。従業員と上司が合意に達した後、残業が可能です。残業が完了したら、従業員は工数システムに残業時間を記入し、システムで残業プロセスを提出します。備考には残業タスクを明確に記載し、作業場所での出退勤記録を完全に記録します。チームリーダー/上司が残業成果を検収した後、残業申請プロセスを承認します。HRが出退勤記録を確認した後、休暇の計算を行います。",
"medias": [
{
"type": "image",
"name": null,
"url":"http://localhost:3978/openapi/chat/media/image/FE680A9CCFB1B56E80737FB28562DC33F4A37DEF52A65F046464788B83E0BE77"
},
{
"type": "file",
"name": "回答参考ファイル.pdf",
"url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"
},
],
"suggestionQuestions": [],
"thoughts": [
{
"thought": "この質問に答えるために、ナレッジベースの関連情報を検索する必要があります。",
"pluginName": "Search Knowledgebase",
"elapsedTime": {
"model": 3612.4722,
"action": 689.5891,
"total": 4302.0613
},
"state": "success"
}
],
"finish_reason": "stop"
},
"success": true,
"msg": ""
}
- 流式响应示例：
data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[],"suggestionQuestions":[],"thoughts":[{"thought":"为了回答这个问题，我需要查询知识库中的相关信息。","pluginName":"Search Knowledgebase","elapsedTime":{"model": 3612.4722,"action": 689.5891,"total": 4302.0613},"state": "success"}],"finish_reason":null},"success":true,"msg":""}
data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"チームリーダーは作業タスクを発表し、完了の期限と検収基準を明確にします。従業員は上 司と合意した後に残業が可能です。残業が終わったら、従業員は工数システムに残業時間を記入し、システムで残業プロセスを提出します。備考には残業タスクを明確に記載し、勤務地での出退勤記録を完全に記録します。チームリーダー/上司が残業成果を検収した後、残業申請プロセスを承認します。HRは打刻記録を確認し、代休の計算を行います。","medias":[],"suggestionQuestions":[],"thoughts":[],"finish_reason":null},"success":true,"msg":""}
data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[{"type":"image","name":null,"url":"http://localhost:3978/openapi/chat/media/image/FE680A9CCFB1B56E80737FB28562DC33F4A37DEF52A65F046464788B83E0BE77"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":null},"success":true,"msg":""}
data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[{"type":"file","name":"答案参考文件.pdf","url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":"stop"},"success":true,"msg":""}
会話の参考資料を取得
-
インターフェースアドレス：
/openapi/chat/record/{chatRecordId}/reference -
リクエスト方法：
get -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| Authorization | はい | string | SERVICEMEアク セストークンを入力、値の形式：openapi {access_token} |
- リクエストURLパラメータ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| chatRecordId | はい | string | 質問応答インターフェースから取得したchatRecordIdフィールドの値 |
- リクエスト例：
curl --location 'http://localhost/openapi/chat/record/4299234148041625600/reference' \
--header 'Authorization: openapi {access_token}'
- レスポンスボディ：
| パラメータ名 | サブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|
| data | object array | レスポンスデータ | |
| title | string | タイトル | |
| content | string | この会話記録で引用された内容 | |
| score | float | 関連度（0から1、1に近いほど関連性が高い） | |
| url | string | リンク（現在はファイルタイプの引用のみリンクがある） | |
| type | string | タイプの列挙：document（文書）、image（画像）、QnA、other | |
| success | boolean | 成功かどうか | |
| msg | string | successがfalseの場合、エラーメッセージが表示される |
- レスポンス例：
{
"data": [
{
"title": "会社の行政制度.pdf",
"content": "セクション1 ......",
"score": 0.95,
"url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
"type": "document"
},
{
"title": "会社の行政制度.pdf",
"content": "セクション2 ......",
"score": 0.81,
"url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
"type": "document"
},
{
"title": "会社の行政制度.pdf",
"content": "セクション3 ......",
"score": 0.76,
"url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
"type": "document"
}
],
"success": true,
"msg": ""
}
ファイルスペース
単一ファイルのアップロード
-
インターフェースアドレス：
v1/openapi/workspace/file/upload -
リクエスト方法：
post -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
| ------------- | ---- | ------ | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- Content Type：
form-data - リクエストボディ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| workspace | はい | string | ファイルスペース |
| file | はい | file | ファイル（単一） |
| eponymousCover | いいえ | bool | 同名ファイルが存在する場合に上書きするか（デフォルトは上書きしない） |
- リクエスト例：
curl --location 'http://localhost/v1/openapi/workspace/file/upload' \
--header 'Authorization: openapi {access_token}' \
--form 'workspace="テストスペース"' \
--form 'file=@"/C:/test.doc"' \
--form 'eponymousCover="false"'
- レスポンスボディ：
| パラメータ名 | サブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|
| data | object | レスポンスデータ | |
| fileId | string | ファイルID | |
| fileName | string | ファイル名 | |
| uploader | string | アップロード者 | |
| success | boolean | 成功かどうか | |
| msg | string | successがfalseの場合、エラーメッセージが表示される |
- レスポンス例：
{
"data": {
"fileId": "4345229404125790208",
"fileName": "test.doc",
"uploader": "test@serviceme.com"
},
"success": true,
"msg": ""
}
複数ファイルのアップロード
ファイルの提出
-
インターフェース アドレス：
v1/openapi/workspace/file/upload/batchSubmit -
リクエスト方法：
post -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
| ------------- | ---- | ------ | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- Content Type：
form-data - リクエストボディ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| workspace | はい | string | ファイルスペース |
| files | はい | file | ファイル（複数） |
| eponymousCover | いいえ | bool | 同名ファイルが存在する場合に上書きするか（デフォルトは上書きしない） |
- リクエスト例：
curl --location 'http://localhost/v1/openapi/workspace/file/upload/batchSubmit' \
--header 'Authorization: openapi {access_token}' \
--form 'workspace="テストスペース"' \
--form 'files=@"/C:/test1.doc"' \
--form 'files=@"/C:/test2.docx"' \
--form 'eponymousCover="false"'
- レスポンスボディ：
| パラメータ名 | サブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|
| data | object | レスポンスデータ | |
| stateId | string | アップロードの状態ID、この状態IDを使用して最新のアップロード結果を取得可能 | |
| success | boolean | 成功かどうか | |
| msg | string | successがfalseの場合、エラーメッセージが表示される |
- レスポンス例：
{
"data": {
"stateId": "4345229404125790208"
},
"success": true,
"msg": ""
}
アップロード結果の確認
-
インターフェースアドレス：
v1/openapi/workspace/file/upload/batchSubmit/{stateId} -
リクエスト方法：
get -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
| ------------- | ---- | ------ | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- リクエストURLパラメータ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| stateId | はい | string | 複数ファイル提出アップロードインターフェースから取得したstateIdフィールドの値 |
- リクエスト例：
curl --location 'http://localhost/v1/openapi/workspace/file/upload/batchSubmit/4345227891722682368' \
--header 'Authorization: openapi {access_token}'
- レスポンスボディ：
| パラメータ名 | サブパラメータ | タイプ | パラメータ説明 |
|---|---|---|---|
| data | object array | レスポンスデータ | |
| fileId | string | ファイルID | |
| fileName | string | ファイル名 | |
| state | string | 状態の列挙：underway（処理中）、success（成功）、fail（失敗） | |
| uploader | string | アップロード者 | |
| errorMsg | string | 状態がfailの場合、失敗の原因がここに表示される | |
| finishTime | string | ファイル処理完了時間 | |
| success | boolean | 成功かどうか | |
| msg | string | successがfalseの場合、エラーメッセージが表示される |
- レスポンス例：
{
"data": [
{
"fileId": "4345227925730099200",
"fileName": "test1.doc",
"state": "success",
"uploader": "test@serviceme.com",
"errorMsg": "",
"finishTime": "2024-08-17T05:04:30.0128596Z"
},
{
"fileId": "4345227924266287104",
"fileName": "test2.docx",
"state": "success",
"uploader": "test@serviceme.com",
"errorMsg": "",
"finishTime": "2024-08-17T05:04:29.7952274Z"
}
],
"success": true,
"msg": ""
}
QnAの作成
-
インターフェースアドレス：
v1/openapi/workspace/qna/create -
リクエスト方法：
post -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
| ------------- | ---- | ------ | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- リクエストボディ：
| パラメータ名 | サブパラメータ | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|---|
| workspace | はい | string | ファイルスペース | |
| questions | はい | string array | 質問の配列、複数可 | |
| answer | はい | string | 答え | |
| metadatas | いいえ | object array | メタデータ | |
| typeCode | はい | string | メタデータのタイプ | |
| content | はい | string | 内容 |
- リクエスト例：
curl --location 'http://localhost/v1/openapi/workspace/qna/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: openapi {access_token}' \
--data '{
"questions": [
"テスト質問"
],
"answer": "テスト回答",
"workspace": "テストスペース",
"metadatas": [
{
"typeCode": "ドキュメントタイプ",
"content": "テストメタデータ"
}
]
}'
- レスポンスボディ：
| パラメータ名 | タイプ | パラメータ説明 |
|---|---|---|
| success | boolean | 成功かどうか |
| msg | string | successがfalseの場合、エラーメッセージが表示される |
- レスポンス例：
{
"success": true,
"msg": ""
}
ファイルの検索
- **インターフェースアドレス：**```v1/openapi/workspace/file```
- **リクエスト方法：**```post```
- **リクエストヘッダー：**
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
| ------------- | ---- | ------ | ------------------------------------------------------------ |
| Authorization | はい | string | SERVICEMEアクセストークンを入力、値の形式：openapi `{access_token}` |
- **リクエストボディ：**
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
| --------- | ---- | ------ | ------------------ |
| workspace | はい | string | ファイルスペース |
| pageIndex | いいえ | number | ページ番号、デフォルトは最初のページ |
| pageSize | いいえ | number | 取得数、デフォルトは10件 |
- **リクエスト例：**
```shell
curl --location 'http://localhost/v1/openapi/workspace/file' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"workspace": "テストスペース",
"pageIndex": 1,
"pageSize": 10
}'
-
レスポンスボディ：
パラメータ名 サブパラメータ サブサブパラメータ タイプ パラメータ説明 data object array レスポンスデータ id string ファイルID name string ファイル名 size number ファイルサイズ（バイト単位） description string 説明 fullPath string ファイルパス tags object array ファイルタグ情報 id string タグID value string タグ内容 chunkingState string ファイルインデックス状態：waiting（処理待ち）、success（成功）、fail（失敗）、underway（進行中） previewState string ファイルプレビュー状態：waiting（処理待ち）、success（成功）、fail（失敗）、underway（進行中） fileCanPreview boolean ファイルがプレビュー可能かどうか、true：可能；false：不可能 previewUrl string ファイルプレビューURL createdByRealName string ファイル作成者名 createdByAccount string ファイル作成者アカウント created datetime ファイル作成日時 modifiedByRealName string ファイル編集者名 modifiedByAccount string ファイル編集者アカウント modified datetime ファイル編集日時 success boolean 成功かどうか msg string successがfalseの場合、エラーメッセージが表示される -
レスポンス例：
{
"data": [
{
"id": "4339013367831199744",
"name": "test.docx",
"size": 15113,
"description": null,
"fullPath": "/",
"tags": [],
"chunkingState": "success",
"previewState": "success",
"fileCanPreview": true,
"previewUrl": "http://localhost.com/#/share/preview?fileId=4339013367831199744&objectType=2&previewType=file&mode=login",
"createdByRealName": "test",
"createdByAccount": "test",
"created": "2024-07-31T01:30:02.88",
"modifiedByRealName": "test",
"modifiedByAccount": "test",
"modified": "2024-07-31T01:30:02.88"
}
],
"pageSize": 10,
"pageIndex": 1,
"totalCount": 1,
"success": true,
"msg": ""
}
ファイルチャンクのクエリ
-
インターフェースアドレス：
v1/openapi/workspace/file/chunk -
リクエスト方法：
post -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| Authorization | はい | string | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- リクエストボディ：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| fileId | はい | string | ファイルID |
| imageFormat | いいえ | string | 画像フォーマット、markdownまたはhtml、デフォルトはmarkdown出力 |
| pageIndex | いいえ | number | ページ番号、デフォルトは最初のページ |
| pageSize | いいえ | number | 取得数、デフォルトは10件 |
- リクエスト例：
curl --location 'http://localhost/v1/openapi/workspace/file/chunk' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"fileId": "4344174161665458176",
"imageFormat": "html",
"pageIndex": 1,
"pageSize": 10
}'
-
レスポンスボディ：
パラメータ名 サブパラメータ サブサブパラメータ タイプ パラメータ説明 data object array レスポンスデータ id string チャンクID content string チャンク内容 success boolean 成功かどうか msg string successがfalseの場合、エラーメッセージが表示される -
レスポンス例：
{
"data": [
{
"id": "4339013367831199744",
"content": "test"
}
],
"pageSize": 10,
"pageIndex": 1,
"totalCount": 1,
"success": true,
"msg": ""
}
RAG
-
インターフェースアドレス：
/v1/openapi/rag -
リクエスト方法：
post -
リクエストヘッダー：
| パラメータ名 | 必須 | タイプ | パラメータ説明 |
|---|---|---|---|
| Authorization | はい | string | SERVICEMEアクセストークンを入力、値の形式：openapi {access_token} |
- リクエストボディ：
| パラメータ名 | タイプ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
query | string | いいえ | 無 | 検索する質問や内容。Keywordsパラメータと両方ともnullにはできません。 |
keywords | string | いいえ | 無 | キーワード、複数のキーワードは | で区切ります。Queryパラメータと両方ともnullにはできません。nullの場合は必要に応じてキーワードを抽出し、指定されている場合はそのキーワードを使用します。 |
workspaces | array | いいえ | 無 | 今回のRAGで検索するファイルスペース名またはID。これを指定した場合、これらのスペースのみから検索します。 |
ragObject | RagObject | はい | 0 | RAGオブジェクトタイプ、列挙値（RagObject列挙を参照）。 |
topk | number | はい | 無 | 返される結果の数。 |
minSimilarity | double | いいえ | 0.8 | 最低類似度、範囲は [0, 1]。 |
metadataFilter | array | いいえ | 無 | 使用するメタデータフィルタータイプ。 現在はdefaultフィルターのみサポート |
ragMode | SearchMode | はい | 0 | RAGモード、列挙値（SearchMode列挙を参照）。 |
weights | object | いいえ | 無 | 各インデックスのRRF重み、RagModeがHybridの場合にのみ有効。nullの場合はデフォルトの重みを使用します。 |
reranker | string | いいえ | 無 | nullの場合はrerankerを使用しません。 |
- リクエスト例：
curl --location 'http://localhost/v1/openapi/rag' \
--header 'Authorization: ••••••' \
--header 'Content-Type: application/json' \
--data '{
"query": "人工知能とは何ですか？",
"keywords": "AI|機械学習",
"workspaces": ["workspace1", "workspace2"],
"ragObject": 2,
"topk": 3,
"minSimilarity": 0.85,
"metadataFilter": ["default"],
"ragMode": 0,
"weights": {
"Embedding": 0.9,
"FullText": 0.8
},
"reranker": "default"
} '
- レスポンスボディ：
| フィールド名 | タイプ | 説明 |
|---|---|---|
data | object | レスポンスデータオブジェクト、検索結果や検索IDなどの情報を含む。 |
data.results | array | 検索結果リスト、各要素はチャンク情報を含むオブジェクト。 |
data.results[].chunkId | string | チャンクID |
data.results[].fileId | string | チャンクが属するファイルID |
data.results[].fileName | string | チャンクが属するファイル名 |
data.results[].content | string | チャンク内容 |
data.results[].metadata | json | チャンクメタデータ |
data.results[].url | string | チャンクのURLアドレス（ある場合） |
data.results[].searchScore | double | 類似度スコア |
data.results[].rrfScore | double | RRFスコア |
data.results[].rerankScore | double | リランクスコア |
data.results[].workspaceId | string | ファイルが属するファイルスペースID |
data.results[].workspaceName | string | ファイルが属するファイルスペース名 |
data.searchId | string | 今回の検索操作の一意識別子 |
success | boolean | リクエストが成功したかどうか |
msg | string | リクエストのメッセージ（ある場合） |
- レスポンス例：
{
"data": {
"results": [
{
"chunkId": "4422442085118906369",
"fileId": "4417076017114382336",
"fileName": "ファイル1.pdf",
"content": "……",
"metadata": {
"Url": "https://……",
"FileName": "ファイル1.pdf",
"WorkspaceName": "workspace1",
"FileId": "4417076017114382336",
"FilePath": "/",
"Created": "2025-03-03T11:23:08.803",
"Size": "1160594"
},
"url": "https://……",
"searchScore": 0.153852914388501,
"rrfScore": 0.8768274796195331,
"rerankScore": 0.0,
"workspaceId": "4417069258022846464",
"workspaceName": ""
},
{
"chunkId": "4422442085114712073",
"fileId": "4417076017114382336",
"fileName": "ファイル1.pdf",
"content": "……",
"metadata": {
"Url": "https://……",
"FileName": "ファイル1.pdf",
"WorkspaceName": "workspace1",
"FileId": "4417076017114382336",
"FilePath": "/",
"Created": "2025-03-03T11:23:08.803",
"Size": "1160594"
},
"url": "https://……",
"searchScore": 0.152822583517241,
"rrfScore": 0.8670604574184315,
"rerankScore": 0.0,
"workspaceId": "4417069258022846464",
"workspaceName": ""
},
{
"chunkId": "4422442085114712071",
"fileId": "4417076017114382336",
"fileName": "ファイル1.pdf",
"content": "……",
"metadata": {
"Url": "……",
"FileName": "ファイル1.pdf",
"WorkspaceName": "workspace1",
"FileId": "4417076017114382336",
"FilePath": "/",
"Created": "2025-03-03T11:23:08.803",
"Size": "1160594"
},
"url": "……",
"searchScore": 0.153708375384407,
"rrfScore": 0.8661891817471927,
"rerankScore": 0.0,
"workspaceId": "4417069258022846464",
"workspaceName": ""
}
],
"searchId": "4423568945336811520"
},
"success": true,
"msg": ""
}
- 列挙型
RagObject 列挙
| 列挙値 | 列挙番号 | 説明 |
|---|---|---|
Both | 0 | Q&A と文書内容を同時に検索。 |
Qna | 1 | Q&A 内容のみを検索。 |
Doc | 2 | 文書内容のみを検索。 |
SearchMode 列挙
| 列挙値 | 列挙番号 | 説明 |
|---|---|---|
Hybrid | 0 | ハイブリッド検索モード、埋め込みベクトルと全文検索を組み合わせる。 |
Embedding | 1 | 埋め込みベクトルに基づく検索モードのみ。 |
FullText | 2 | 全文検索に基づく検索モードのみ。 |