# API リファレンス
<a name="api-reference"></a>

このセクションでは、ソリューションの API リファレンスを提供します。

## デプロイダッシュボード
<a name="deployment-dashboard-3"></a>


| REST API | HTTP メソッド | 機能 | 認可された呼び出し元 | 
| --- | --- | --- | --- | 
|   `/deployments`   |   `GET`   |  すべてのデプロイを取得します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/deployments`   |   `POST`   |  新しいユースケースのデプロイを作成します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/deployments/{useCaseId}`   |   `GET`   |  1 つのデプロイのデプロイ詳細を取得します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/deployments/{useCaseId}`   |   `PATCH`   |  指定されたデプロイを更新します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/deployments/{useCaseId}`   |   `DELETE`   |  指定されたデプロイを削除します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/model-info/use-case-types`   |   `GET`   |  デプロイで使用できるユースケースタイプを取得します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/model-info/{useCaseType}/providers`   |   `GET`   |  指定されたユースケースタイプで使用可能なモデルプロバイダーを取得します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/model-info/{useCaseType}/{providerName}`   |   `GET`   |  指定されたプロバイダーとユースケースタイプで使用可能なモデルの ID を取得します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/model-info/{useCaseType}/{providerName}/{modelId}`   |   `GET`   |  指定されたモデルに関する情報 (デフォルトのパラメータを含む) を取得します。  |  Amazon Cognito 認証済み JWT トークン  | 

**注記**  
API との統合を容易にするため、OpenAPI ファイルと Swagger ファイルを API Gateway からエクスポートすることもできます。「[API Gateway から REST API をエクスポートする](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html)」を参照してください。

 **POST ペイロードと PATCH ペイロード** 

新しいユースケースを作成する`/deployments` エンドポイントへの POST ペイロードの例については、以下を参照してください。

```
{
 "UseCaseName": "usecase1",
 "UseCaseDescription": "Description of the use case to be deployed. For display purposes", // optional
 "DefaultUserEmail": "placeholder@example.com", // optional, if not provided, the Cognito Group and User will not be created
 "DeployUI": true, // optional
 "VpcParams": {
 "VpcEnabled": true,
 "CreateNewVpc": false,
 // provide these if not creating new vpc
 "ExistingVpcId": "vpc-id",
 "ExistingPrivateSubnetIds": ["subnet-1", "subnet-2"],
 "ExistingSecurityGroupIds": ["sg-1", "sg-2"]
 },
 "ConversationMemoryParams": {
 "ConversationMemoryType": "DynamoDB",
 "HumanPrefix": "user", // optional
 "AiPrefix": "ai", // optional
 "ChatHistoryLength": 10 // optional
 },
 "KnowledgeBaseParams": {
 "KnowledgeBaseType": "Bedrock",
 // one of the following based on selected provider
 "BedrockKnowledgeBaseParams": {
 "BedrockKnowledgeBaseId": "my-bedrock-kb",
 "RetrievalFilter": {}, // optional
 "OverrideSearchType": "HYBRID" // optional
 },
 "KendraKnowledgeBaseParams": {
 "AttributeFilter": {}, // optional
 "RoleBasedAccessControlEnabled": true, // optional
 "ExistingKendraIndexId": "12345678-abcd-1234-abcd-1234567890ab",
 // provide the following in place of ExistingKendraIndexId if you want the solution to deploy an index for you
 "KendraIndexName": "index",
 "QueryCapacityUnits": 1, // optional
 "StorageCapacityUnits": 1, // optional
 "KendraIndexEdition": "DEVELOPER" // optional
 },
 "NoDocsFoundResponse": "Sorry, I couldn't find any relevant information for your query.", // optional
 "NumberOfDocs": 3, // optional
 "ScoreThreshold": 0.7, // optional
 "ReturnSourceDocs": true // optional
 },
 "LlmParams": {
 "ModelProvider": "Bedrock | SAGEMAKER",
 // one of the following based on selected provider
 "BedrockLlmParams": {
 "ModelId": "model-id", // use this for on demand models. Can't use with ModelArn
 "ModelArn": "model-arn", // use this for provisioned/custom models. Can't use with ModelId,
 "InferenceProfileId": "profile-id"
 "GuardrailIdentifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/my-guardrail", // optional
 "GuardrailVersion": "1" // optional. Required if GuardrailIdentifier provided.
 },
 "SageMakerLlmParams": {
 "EndpointName": "some-endpoint",
 "ModelInputPayloadSchema": {},
 "ModelOutputJSONPath": "$."
 },
 // optional. Passes on arbitrary params to the underlying LLM.
 "ModelParams": {
 "param1": {
 "Value": "value1",
 "Type": "string"
 },
 "param2": {
 "Value": 1,
 "Type": "integer"
 }
 },
 // optional
 "PromptParams": {
 "PromptTemplate": "some template",
 "UserPromptEditingEnabled": true,
 "MaxPromptTemplateLength": 1000,
 "MaxInputTextLength": 1000,
 "DisambiguationPromptTemplate": "some disambiguation template",
 "DisambiguationEnabled": true
 },
 "Temperature": 1.0, // optional
 "Streaming": true, // optional
 "RAGEnabled": true, // optional. Must be true if providing KnowledgeBaseParams above.
 "Verbose": false // optional
 },
 "AgentParams": {
 "AgentType": "Bedrock",
 "BedrockAgentParams": {
 "AgentId": "agent-id",
 "AgentAliasId": "alias-id",
 "EnableTrace": true
 }
 },
 // optional
 "AuthenticationParams": {
 "AuthenticationProvider": "Cognito",
 "CognitoParams": {
 "ExistingUserPoolId": "user-pool-id",
 "ExistingUserPoolClientId": "client-id" // optional. If not provided, the solution will create a client for you in the provided pool
 }
 }

}
```

更新の場合、構造は上記と同じですが、いくつかの注意点があります。
+ ユースケース名は変更できません
+ ユースケースが VPC にデプロイされた後は、セキュリティグループとサブネットのみ変更できます。VPC 自体は変更できません。
+ ナレッジベースとして Kendra インデックスが作成された場合、そのインデックスの設定 (KendraIndexName、QueryCapacityUnits など) を変更することはできません。

## 共有ユースケース API
<a name="shared-use-case-apis"></a>

Text と Bedrock エージェントの両方のユースケースで、次の REST API エンドポイントを使用できます。


| REST API | HTTP メソッド | 機能 | 認可された呼び出し元 | 
| --- | --- | --- | --- | 
|   `/details/{useCaseConfigKey}`   |   `GET`   |  特定のユースケースの設定の詳細を取得します。  |  Amazon Cognito 認証済み JWT トークン  | 


| WebSocket API | 機能 | 認可された呼び出し元 | 
| --- | --- | --- | 
|   `/$connect`   |  WebSocket 接続を開始し、ユーザーを認証します。  |  Amazon Cognito 認証済み JWT トークン  | 
|   `/$disconnect`   |  WebSocket 接続が切断されたときに呼び出されるエンドポイント。  |  Amazon Cognito 認証済み JWT トークン  | 

 **ユースケースの詳細 API** 

詳細 API エンドポイントは、特定のユースケースに関する情報を取得します。

```
GET /details/{useCaseConfigKey}
```

このエンドポイントは、モデルパラメータ、ナレッジベース設定、その他のデプロイ情報など、特定のユースケースの設定の詳細を返します。承認には Amazon Cognito 認証 JWT トークンが必要です。

## Text ユースケース
<a name="chat-use-case-2"></a>


| WebSocket API | 機能 | 認可された呼び出し元 | 
| --- | --- | --- | 
|   `/sendMessage`   |  ユーザーのチャットメッセージを WebSocket に送信し、設定済みの LLM エクスペリエンスで処理します。  |  Amazon Cognito 認証済み JWT トークン  | 


| REST API | HTTP メソッド | 機能 | 認可された呼び出し元 | 
| --- | --- | --- | --- | 
|   `/feedback/{useCaseId}`   |   `POST`   |  特定のユースケースに関するユーザーフィードバックを送信します。  |  Amazon Cognito 認証済み JWT トークン  | 

 **sendMessage ペイロード** 

`/sendMessage` API と直接統合する場合は、次のリクエストおよびレスポンスペイロード形式に従う必要があります。

 *リクエストペイロード* 

```
{
 "action": "sendMessage",
 "question": "the message to send to the api",
 "conversationId": "", // If not provided, a new conversation will be created, with the conversationId returned in the response. All subsequent messages in that conversation (where history is retained), should provide the conversationId there.
 "promptTemplate": "", // Optional. Overrides the configured prompt
 "authToken": "XXXX" // Optional. accessToken from cognito flow. Required for RAG with RBAC
}
```


| Parameter Name | 型 | 説明 | 
| --- | --- | --- | 
|   **action**   |   `String`   |  現在、WebSocket では "sendMessage" アクションのみをサポートしています。  | 
|   **question**   |   `String`   |  LLM に送信するユーザー入力。  | 
|   **conversationId**   |   `String`   |  会話を識別する UUID。指定しない場合は新しい会話が作成され、その conversationId が応答で返されます。その会話の後続のすべてのメッセージで履歴やコンテキストを保持する場合は、そこに conversationId が提供されます。  | 
|   **promptTemplate**   |   `String` [オプション]  |  このメッセージ用のプロンプトテンプレートを上書きします。空または指定されていない場合、デプロイ時に設定されたデフォルトのプロンプトが使用されます。指定する場合は、設定に応じて適切なプレースホルダーを含める必要があります (例: RAG なしの Sagemaker AI デプロイの場合は \$1history\$1 と \$1input\$1、すべてのデプロイに RAG ありの場合は \$1context\$1 を追加する)。  | 
|   **authToken**   |   `String` [オプション]  |  Cognito 認証フローから取得された accessToken。ロールベースのアクセスコントロール (RBAC) を使用して RAG 用に設定されたチャット WebSocket エンドポイントを呼び出すときに必要です。この JWT トークンの cognito:groups クレームリストは、Kendra インデックス内のドキュメントへのアクセス制御に使用されます。このパラメータは、RAG なしのユースケースには**必要ありません**。また、RAG ありのユースケースでも、RBAC が無効になっている場合はは**必要ありません**。  | 

 *レスポンスペイロード* 

 *質問に対する応答* 

WebSocket API は、各クエリに対して次のように構造化された JSON オブジェクトで応答します。ストリーミングが無効になっている場合は 1 件、ストリーミングが有効になっている場合は複数件のオブジェクトが返されます。

```
{
 "data": "some data",
 "conversationId": "id",
}
```


| Parameter Name | 型 | 説明 | 
| --- | --- | --- | 
|   **data**   |   `String`   |  ストリーミングが有効な場合は LLM からの応答の一部、無効な場合はまたは応答全体が含まれます。ストリーミングを使用している場合、データの内容が *END\$1CONVERSATION* となっているものこの形式の応答で送信され、1 つの質問に対する応答の終了を示します。  | 
|   **conversationId**   |   `String`   |  この sourceDocument の応答が属する会話の ID。  | 

 *ソースドキュメントの応答* 

ソースドキュメントを返すように RAG ユースケースを設定している場合、応答の生成に使用された各ソースドキュメントについて、次のペイロードがすべての応答の末尾に返されます。

```
{
 "sourceDocument": {
 "excerpt": "some excerpt from the",
 "location": "s3://fake-bucket/test.txt",
 "score": 0.500,
 "document_title": null,
 "document_id": null,
 "additional_attributes": null
 },
 "conversationId": "some-id"
}
```


| Parameter Name | 型 | 説明 | 
| --- | --- | --- | 
|   **excerpt**   |   `String`   |  ソースドキュメントからの抜粋。  | 
|   **location**   |   `String`   |  ソースドキュメントの場所。使用されるデータソースとナレッジベースのタイプによって異なりますが、S3 の URI やウェブサイトなどです。  | 
|   **score**   |   `Number` \$1 `String`   |  質問に対する関連度スコア。Bedrock の場合は 0～1 の浮動小数点数、Kendra の場合は HIGH、LOW などの文字列になります。  | 
|   **document\$1title**   |   `String`   |  返されたソースドキュメントのタイトル。Kendra を使用する場合にのみ返されます。  | 
|   **document\$1id**   |   `String`   |  返されたソースドキュメントの ID。Kendra を使用する場合にのみ返されます。  | 
|   **additional\$1attributes**   |   `String`   |  このフィールドには、取り込み時にナレッジベースでカスタマイズされたドキュメント上のすべての追加属性が含まれます。  | 
|   **conversationId**   |   `String`   |  この sourceDocument の応答が属する会話の ID。  | 

 **フィードバック API ペイロード** 

以下は、特定のユースケースに関するユーザーフィードバックを送信する `/feedback/{useCaseId}` エンドポイントへの POST ペイロードの例です。

```
{
  "useCaseRecordKey": "12345678-12345678",
  "conversationId": "12345678-1234-1234-1234-123456789012",
  "messageId": "12345678-1234-1234-1234-123456789012",
  "feedback": "positive",
  "feedbackReason": ["accurate", "helpful"],
  "comment": "This response was very helpful.",
  "rephrasedQuery": "What are the key features of Amazon Bedrock?",
  "sourceDocuments": [
    "s3://bucket-name/document1.pdf",
    "s3://bucket-name/document2.pdf"
  ]
}
```

## Bedrock エージェントユースケース
<a name="agent-use-case-2"></a>


| WebSocket API | 機能 | 認可された呼び出し元 | 
| --- | --- | --- | 
|   `/invokeAgent`   |  ユーザーのメッセージを WebSocket に送信し、設定されたエージェントで処理します。  |  Amazon Cognito 認証済み JWT トークン  | 

### invokeAgent ペイロード
<a name="invokeagent-payloads"></a>

`/invokeAgent API` と直接統合する場合は、次のリクエストおよびレスポンスペイロード形式に従う必要があります。

 *リクエストペイロード* 

```
{
"action": "invokeAgent",
"inputText": "User query to the agent",
"conversationId": "", // Optional. Empty conversationId implies a new conversation. When not provided, a new conversationId will be created and returned with the response. All subsequent messages in the same conversation should provide the same conversationId (i.e. chat memory/history is maintained).
"authToken": "XXXX" // Optional. accessToken from cognito flow. If provided, it needs to be a valid JWT token associated with the user
}
```


| パラメータ名 | 型 | 説明 | 
| --- | --- | --- | 
|   **action**   |   `String`   |  WebSocket では `invokeAgent` アクションのみをサポートしています。  | 
|   **inputText**   |   `String`   |  LLM に送信するユーザー入力。  | 
|   **conversationId**   |   `String[Optional]`   |  会話を一意に識別する UUID。この値を指定しない場合、ソリューションは新しい会話を作成し、レスポンスに **conversationId** が返されます。その会話の後続のすべてのメッセージで履歴やコンテキストを保持する場合は、そこに **conversationId** が提供されます。  | 
|   **authToken**   |   `String[Optional]`   |   Amazon Cognito 認証フローから取得された **accessToken**。このパラメータは**必須ではありません**。これを指定すると、JWT トークンが検証されます。これにより、このソリューションの拡張が容易になります。  | 

 *レスポンスペイロード* 

 *質問に対する応答* 

WebSocket API は、各クエリに対して次のように構造化された JSON オブジェクトで応答します。ストリーミングが無効になっている場合は 1 件、ストリーミングが有効になっている場合は複数件のオブジェクトが返されます。

```
{
 "data" "some data",
 "conversationId": "id",
 }
```


| パラメータ名 | 型 | 説明 | 
| --- | --- | --- | 
|   **data**   |   `String`   |  エージェント呼び出しからの応答。  | 
|   **conversationId**   |   `String`   |  会話の ID。  |