カスタムコネクタの構成オプションについて確認する

8 分

このユニットでは、引き続きカスタムコネクタの基本を説明し、利用可能な構成オプションのいくつかを詳しく紹介します。

コネクタの命名と全般情報

最初に決めることの 1 つは、コネクタの名前です。一意な名前を指定し、どのようなコネクタであるかを利用者にわかりやすく伝える必要があります。この名前に使用できる文字数は 30 文字までで、詳しい説明は説明フィールドに追加できます。 アイコンの背景色フィールドは、コネクタを視覚的に識別するのにも役立ちます。これらのフィールドは、ユーザーが使用するコネクタを選択する際に表示され、ユーザーが効率よく作業するための視覚的なヒントとなります。認定資格を受けるためにコネクタの提出を計画している場合は、コネクタを Microsoft に提出する手順ドキュメントに記載されているより厳格な要件を確認します。

アクションおよびトリガーの命名

ユーザーは、コネクタを絞り込み選んだ後で、コネクタから使用するアクションまたはトリガーを選択します。 操作 ID、概要、および説明フィールドは、各アクションとトリガーを説明するのに役立ちます。操作 ID は内部で使用されるもので、一意である必要があります。スペースを含めることはできません。キャメルケース (GetInvoice など) を使用すると、定義のマークアップを確認する場合に ID を簡単に読み取れるようになります。名前にスペースがないのは、スクリーンリーダーを使用する作成者にとっては扱いにくいかもしれませんが、キャメルケースを使用することで、作成者は定義を簡単に理解し利用することが可能になります。

概要フィールドが重要な理由は、使用するアクションやトリガーを選択する際に、アクションおよびトリガーの一覧にこのフィールドが表示されるためです。アクションやトリガーの機能がわかるように、適切な説明を指定することをお勧めします。たとえば、GetInvoice アクションの説明を ID により特定の請求書を取得とすることができます。作成者は検索でアクションを探すことが多いため、動作を説明するような名前にすると、適切なアクションを見つけやすくなります。

次の画像は、アクションまたはトリガーを選択するときに、概要要素と説明要素が使用される場所を示しています。

アクションまたはトリガーを選択すると、デザイナーの各アクションカードに概要と説明の両方の要素が表示されます。

前の画像で、命名パターンが一貫していないことに注意してください。概要には、スペースを含む名前もあれば、スペースを含まない名前もあります。このエラーを修正するには、ポータルのフィールドを更新します。または、API を所有している場合は、インポートする OpenAPI 定義で提供される情報の更新を開発者に依頼します。ポータルで手動で変更を行った後に OpenAPI 定義を再度インポートすると、変更が上書きされますので注意してください。

アクションの表示方法

アクションで表示設定オプションを設定すると、作成者にアクションがどう表示されるかを調整できます。

なし - これが既定のオプションです。アクションは通常どおり表示されます。
詳細 - アクションは使用できますが、優先されません。
内部 - アクションは非表示になります。
重要 - アクションは優先され、最初に表示されます。

たとえば、10 のアクションを使用して Open API 定義をインポートし、その中の 2 つをユーザーに最初に表示したくない/使用してほしくない場合は、内部オプションを選択して非表示にします。このアプローチは、動的コネクタメタデータをサポートするのに使用される操作を処理する場合に役立ちます。また、最初はアクションを非表示にし、後でユーザーの要求に応じてアクションとして表示することもできます。アクションを非表示にすると、ユーザーに表示されるリストを最小限にできます。

重要として選択されたアクションが、最初に表示されます。なしまたは詳細が選択されているコネクタを表示するには、ユーザーがコネクタを選択する必要があります。このアプローチは、アクションが多数あり、その多くが頻繁に使用されていない場合に最適です。

要求

要求では、アクションが API の操作を呼び出す際に、どのパラメーター/データが操作に渡されるかが定義されます。 OpenAPI 定義をインポートするときに、要求クエリ、ヘッダー、および本文の設定が構成されます。サンプルからインポートすることで、手動でインポートすることもできます。

次の画像は、定義を探しているときの画面の外観の例を示しています。

この構成は、ユーザーがアクションを使用するときに表示される情報に変換されるため重要です。

各パラメーターを編集するか、API 開発者に詳細の提供を求めることで、アクションを使用する際のユーザーエクスペリエンスを向上できます。各パラメーターで省略記号 (...) を選択すると、次の編集画面が表示されます。

確認および変更する必要があるフィールドおよびオプションは次のとおりです。

名前 - 変更しないでください。このフィールドは、API が予期する設定と一致する必要があります。
概要 - このフィールドには簡単に理解できる情報を指定します。たとえば、日付ではなく終了日と指定します。
説明 - このフィールドには、パラメーターを説明する文が含まれます。フィールドのプレースホルダーテキストとして使用されます。
既定値 - このフィールドは任意の既定値ですが、可視性を内部に設定し、パラメーターを必須にする場合は入力が必要です。
必須 - API に値が必要な場合は、このオプションを設定してください。このオプションを選択すると、フィールドの横に赤いアスタリスクが表示されます。
可視性 - このパラメーターは、前に説明したアクションの表示設定オプションと類似した動作をします。頻繁に使用しないパラメーターがある場合は、詳細オプションを選択します。
種類と書式 - サンプルからインポートするパラメーターは常に正しいとは限らないため、これらのフィールドが適切な値であることを確認します。
ドロップダウンの種類 - このパラメーターを使用して静的または動的な値のリストを構成することで、ユーザーは、より簡単かつ予測可能な選択を行うことができます。

次の画像は、開始日パラメーターを修正後の画面の外観の例を示しています。

応答

応答は、API から返されるものを定義します。単一の定義のみの要求とは異なり、ユーザーは HTTP ステータスに基づいてさまざまな応答を用意できます。たとえば、API 呼び出しによってエラーが生成された場合、本文には API が返す内容の代わりにエラーの詳細が含まれます。特定の HTTP ステータスの応答がない場合、キャッチオール応答の既定の応答も設定できます。