OpenAPI 仕様の統合 - Amazon Quick
できること[開始する前に]OpenAPI 仕様と認証を準備するOpenAPI 仕様統合をセットアップする形式とパターンの要件サポートされていない 機能スキーマのベストプラクティスサポートされる拡張機能スキーマの検証とエラー処理OpenAPI 仕様統合の管理OpenAPI 仕様統合のトラブルシューティング

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

OpenAPI 仕様の統合

OpenAPI 仕様統合を使用すると、OpenAPI スキーマに基づいてカスタム統合を作成できます。これにより、OpenAPI 仕様を提供する任意の API に接続できます。この統合はアクション実行のみをサポートし、Amazon Quick Pro 階層以上が必要です。

できること

OpenAPI 仕様統合は、カスタム APIs。

アクションコネクタ

OpenAPI の仕様に基づいてアクションを実行します。API コールを実行し、リソースを管理し、提供されたスキーマに基づいて動的に生成されたアクションを通じてカスタムサービスとやり取りします。

スキーマベースの設定

OpenAPI 仕様をインポートして、使用可能なアクションとアクションを自動的に生成します。JSON スキーマの検証とパラメータマッピングのサポート。

[開始する前に]

OpenAPI 仕様統合を設定する前に、以下があることを確認してください。

  • ターゲット API の OpenAPI 仕様 (バージョン 3.0.0 以降）。

  • API 認証情報 (API キー、OAuth、その他）。

  • Amazon Quick Author 以上。

  • API ドキュメントとエンドポイントへのアクセス。

OpenAPI 仕様と認証を準備する

Amazon Quick で統合を設定する前に、OpenAPI 仕様と認証情報を準備します。OpenAPI 仕様は、統合を成功させるための特定の要件を満たしている必要があります。

基本要件

OpenAPI 仕様は、これらの基本要件を満たしている必要があります。

  • OpenAPI バージョン - バージョン 3.0.0 以降が必要です。

  • ファイル形式 - JSON 形式のみ (application/json)。

  • ファイルサイズ制限 - OpenAPI 仕様全体の最大 1MB。

  • オペレーション制限 - コネクタごとに最小 1 回、最大 100 回の API オペレーション。

必須スキーマフィールド

OpenAPI 仕様には、これらの必須セクションが含まれている必要があります。

openapi

使用する OpenAPI バージョン (「3.0.0」以降である必要があります）。

info

タイトル、説明、バージョンなどのサービス情報。

サーバー

API 接続の基本 URL とサーバー情報。

パス

HTTP メソッドとオペレーションを使用した API エンドポイント定義。

サポートされている認証スキーム

OpenAPI 仕様でサポートされている認証方法に基づいて認証情報を準備します。

OAuth 2.0

認可コード付与フローとクライアント認証情報付与フローの両方をサポートします。セキュリティスキームで authorizationUrl、tokenUrl、スコープ定義が必要です。

API キー

クエリパラメータまたはヘッダーに渡される API キー認証。

認証なし

仕様でセキュリティスキームが定義されていない場合のデフォルトオプション。

注記

OpenAPI 仕様でサポートされていない認証スキームは無視され、コネクタはデフォルトで認証なしになります。

OpenAPI 仕様統合をセットアップする

OpenAPI 仕様と認証情報を準備したら、以下の手順に従って OpenAPI 仕様統合を作成します。

  1. Amazon Quick コンソールで、統合を選択します。

  2. 追加 (プラス「＋」ボタン) をクリックします。

  3. スキーマの追加ページで、スキーマのインポートを選択し、インポートするスキーマを選択します。

  4. [次へ] を選択してください。

  5. 名前や説明など、統合の詳細を入力します。

  6. OpenAPI 仕様から生成された利用可能なアクションを確認します。

  7. 作成して続行を選択します。

  8. 統合を共有するユーザーを選択します。

  9. [次へ] をクリックします。

予想される結果

セットアップが正常に完了すると、OpenAPI 仕様の統合が統合リストに表示され、スキーマに基づいて動的に生成されたアクションが表示されます。統合は、OpenAPI 仕様で定義されたエンドポイントに対応するタスクを使用して、Amazon Quick ワークフロー、オートメーション、AI エージェントで使用できます。

形式とパターンの要件

OpenAPI 仕様は、これらの形式要件に従う必要があります。

  • パスパターン - パターンに従う必要があります。^/[^/]*(/[^/]*)*$スラッシュ (/) で始まります。

  • オペレーション IDs - パターンに従う必要があります: ^[a-zA-Z0-9_ ]{1,256}$。

  • 説明 - すべてのオペレーションとパラメータに必須で、最大 5000 文字です。

  • コンテンツタイプ - リクエスト本文とレスポンス本文では application/json のみがサポートされています。

サポートされていない 機能

次の OpenAPI 機能はサポートされていないため、検証エラーが発生します。

  • 配列タイプ - 配列タイプ ( など{"type": "array", "items": {"string"}}) を持つスキーマはサポートされていません。

  • コンポジションキーワード - allOf、oneOf、 anyOf、および not キーワードはサポートされていません。

  • 循環参照 - 循環参照または循環参照 ($ref 内の $ref) はサポートされていません。

  • 複雑なネスト構造 - 可能な限り、深くネストされたオブジェクト構造は避けてください。

スキーマのベストプラクティス

OpenAPI 仕様を作成するときは、以下のベストプラクティスに従ってください。

効果的な説明を書く

これらのガイドラインを使用して、明確で有用な説明を記述します。

  • オペレーションの説明 - オペレーションの動作、使用するタイミング、動作について説明します。

  • パラメータの説明 - パラメータの目的とオペレーション動作への影響を簡潔に説明します。

  • 自己完結型コンテンツ - 説明が外部参照なしで十分なガイダンスを提供していることを確認します。

  • 依存関係の明確さ - オペレーション間の依存関係を説明で明確にします。

  • オペレーションリファレンス - API パスではなく、他のオペレーションを参照するときに operationId を使用します。

パラメータ構造の推奨事項

最適なユーザビリティを実現するためにパラメータを構造化します。

  • 複雑なオブジェクトをフラット化する - ネストされたオブジェクトの代わりに、個別のパラメータ (start_date、start_time、end_date、end_time など) を使用します。

  • 標準形式を使用する - ISO-8601 の日時には「date-time」や「date」などの標準形式値を使用します。

  • パラメータ名をクリアする - 目的を明確に示すわかりやすいパラメータ名を使用します。

  • 必須フィールドのマーク - API の動作に基づいて、パラメータを必須またはオプションとして適切にマークします。

サポートされる拡張機能

ユーザーエクスペリエンスを向上させるために、カスタム OpenAPI 拡張機能をサポートしています。

x-amzn-form-display-name

パラメータレベルで を使用して、確認フォームに表示されるデフォルトのフィールド名を上書きします。現在、リクエスト本文パラメータでのみサポートされています。

"x-amzn-form-display-name": "User Name"
x-amzn-operation-type

オペレーションを「読み取り」と「書き込み」のどちらとして扱うかを定義します。デフォルトでは、GET メソッドは「読み取り」オペレーションであり、他のすべての HTTP メソッドは「書き込み」オペレーションです。

"x-amzn-operation-type": "read"

スキーマの検証とエラー処理

OpenAPI 仕様をアップロードすると、包括的な検証が実行されます。

  • ファイルサイズの検証 - 仕様が 1MB を超えないようにします。

  • オペレーション数の検証 - 1～100 個のオペレーションが定義されていることを確認します。

  • スキーマ構造の検証 - 必須フィールドと適切なフォーマットをチェックします。

  • セキュリティスキームの検証 - サポートされている認証方法を検証します。

  • コンテンツタイプの検証 - application/json のみが使用されます。

検証エラーはスキーマエディタの下に表示され、統合を作成する前に解決する必要があります。一般的な検証の問題は次のとおりです。

  • 必須フィールド (openapi、情報、サーバー、パス) がありません。

  • パスパターンまたはオペレーション IDsが無効です。

  • サポートされていないスキーマ機能 (配列、コンポジションキーワード）。

  • 説明がないか、長すぎます。

  • スキーマ定義の循環参照。

OpenAPI 仕様統合の管理

OpenAPI 仕様統合を作成したら、いくつかのオプションを使用して管理できます。

統合の共有

OpenAPI 仕様アクションコネクタは、組織内の他のユーザーと共有できます。

  1. OpenAPI 統合の詳細ページで、共有を選択します。

  2. 共有オプションを設定します。

    • 特定のユーザーと共有 - ユーザー名または E メールアドレスを入力します。

    • 組織と共有 - 組織内のすべてのユーザーが利用できるようにします。

  3. 共有アクセスのアクセス許可レベルを設定します。

  4. 共有統合を選択して共有設定を適用します。

統合の削除

OpenAPI 統合を完全に削除するには、次の手順に従います。

  1. OpenAPI 統合の詳細ページで、削除を選択します。

  2. この統合を使用するワークフローやオートメーションなど、削除の影響を確認します。

  3. 削除を確認するには、統合名を入力します。

  4. 統合の削除を選択して、完全に削除します。

OpenAPI 仕様統合のトラブルシューティング

これらのトラブルシューティングのヒントを使用して、一般的な OpenAPI 仕様統合の問題を解決します。

スキーマ検証エラー

OpenAPI 仕様が正しい形式に従っており、すべての必須フィールドが含まれていることを確認します。OpenAPI 検証を使用して、インポート前にスキーマを確認します。

タスクは生成されません

OpenAPI 仕様に HTTP メソッドとオペレーション IDs を含むパス定義が含まれていることを確認します。アクションは、スキーマで定義されたオペレーションに基づいて生成されます。

認証の失敗

OpenAPI 仕様で定義されている認証スキームが実際の API 要件と一致し、認証情報が正しく設定されていることを確認します。

アクション実行の失敗

アクションパラメータを確認し、必須フィールドやデータ型など、OpenAPI 仕様のパラメータ定義と一致することを確認します。