文字列フィールドのベスト プラクティスを学ぶ

次の記事には、Power Automate、Power Apps、Azure Logic Apps のコネクタ内の文字列フィールドに関する一般的なガイダンスが含まれています。

コネクタ情報

各コネクタには、コネクタの名前であるタイトルと、一般的なコネクタを説明する説明が必要です。 この情報は、OpenAPI 定義 (apiDefinition.swagger.json ファイル内) にある_情報_セクションの_タイトル_と_説明_フィールドに指定する必要があります。

コネクタのタイトルと説明を入力する際には、少なくとも次のガイドラインに従う必要があります:

• コネクタのタイトルには最大 30 文字を使用できます。
• コネクタのタイトルと説明に API という文字を含めることはできません。
• コネクタのタイトルと説明では、Power Platform 製品、またはバックエンド API を所有していない製品を参照することはできません。

認証されたコネクターに適用される、より高い基準のタイトルと説明フィールドのガイドラインは、こちら に掲載されており、ベスト プラクティスとして使用する必要があります。

操作

OpenAPI 定義の各パスと動詞は、操作に対応します。 操作を以下の各文字列/タグで適切に説明することにより、エンド ユーザーは適切に使用できます。 操作の一部の文字列フィールドは次のとおりです。

• summary: これは操作の名前として表示されます。

  • ケース: 文
  • 注:
    • 名前にスラッシュ ('/') は使用できません。
    • 80 文字を超えることはできません。
    • 末尾には英数字以外の文字 (句読点またはスペースを含む) を使用しないでください。

• 説明: 次の画像のように、情報ボタンを選択すると、操作説明として表示されます 。

  • ケース: 文。
  • 注: テキスト ボックスに収まるように短くしてください。 単語が 1 つあれば、ピリオドは必要ありません。

• operationId: これは、操作に関連付けられた一意の ID です。

  • ケース: Camel (スペースや句読点なし)。
  • 注: GetContacts または CreateContact など、操作の意味を伝えるためのものです。

  次の画像は、ワークフロー作成時に表示される、概要—メールの送信、説明—この操作でメールを送信する フィールドの表示方法を示しています。

  

トリガーとアクション

トリガーによりワークフローまたはプロセスが開始されます。 たとえば、「毎週月曜日の午前 3 時にワークフローを開始」、「オブジェクトが作成されたとき」などです。

トリガーの概要フィールドと説明フィールドは、人間が読める形式で意味を持つ必要があります。 Trigger summary は通常"__________________の場合" の形式です。

例:

Trigger description は通常 "この操作は_______________時にトリガーされます" の形式です。

例:

• この操作は、新しいタスクが追加されたときにトリガーされます。

アクションは、"電子メールの送信"、"行の更新"、"通知の送信" など、ワークフロー内の完了すべきタスクです。 action summary のいくつかの例を以下に示します。

パラメーター

各操作 (トリガーまたはアクション) には、ユーザーが入力として指定するパラメーターがあります。 パラメーターの重要な文字列フィールドの一部は次のとおりです。

• x-ms-summary: これはパラメーターの名前として表示されます。

  • ケース: タイトル
  • 注: 80 文字までに制限されています

• description: これは、入力ボックス内のパラメーターの説明として表示されます。

  • ケース: 文
  • 注: テキスト ボックスに収まるように短くしてください。 単語が 1 つあれば、ピリオドは必要ありません。

  下の画像では、ハイライトされているパラメーターの x-ms-summary フィールドの値が "subject" で、説明 が "Specify the subject of the mail" になっています。

  

応答

各操作には、後続の操作の入力として、ワークフローの後半で使用できる応答があります。 結果のスキーマは、複数のプロパティで構成されています。 各パラメーターの重要な文字列フィールドの一部は次のとおりです:

• x-ms-summary: これは結果プロパティの名前として表示されます。

  • ケース: タイトル
  • 注: 短い名前を使用してください。

• description: これは、結果プロパティの説明として表示されます。

  • ケース: 文
  • 注: 短く簡潔にします。末尾にはピリオドが必要です。

  以下の画像では、ワークフローの後続の操作の 1 つで動的コンテンツを追加しようとすると、"フローを手動でトリガーする" 操作の結果スキーマが表示されます。 ここで、"User email" は x-ms-summary で、その下のテキストは "Manually trigger a flow" 操作の応答でのプロパティの description です。

一般的に summary/x-ms-summary および description のフィールドで考慮すべき重要な注意事項は次のとおりです:

• 概要と説明のテキストは同じにしないでください。
• 説明は、ユーザーへの追加情報 (出力形式、プロパティに関連するオブジェクトなど) を提供する目的で使用します。 例: `summary : ID、description: ユーザーの ID。
• 入れ子にされた値を持つオブジェクトでは、親の名前の x-ms-summary が子に追加されます。

x-ms-visibility

ユーザーに対するエンティティの優先度を決定します。 表示優先度を指定しなかった場合は、"通常" 表示と見なされます。 使用可能な値は、"important"、"advanced"、"internal" です。 "internal" とマークされたエンティティは、ユーザー インターフェイスに表示されません。

適用対象:

• 操作
• パラメーター
• 応答のプロパティ

例:

UI では、"important" としてマークされたエンティティが最初に表示され、"advanced" としてマークされたものはトグル (強調表示) の下で非表示になり、"internal" としてマークされたものは表示されません。 次の画像は、既定で「重要」とマークされたパラメータの例です。 また、高度なオプションの表示ボタンを選択すると、「高度な」とマークされたパラメーターが表示されることも示しています。

フィードバックを提供する

コネクタ プラットフォームの問題点や新機能のアイデアなどのフィードバックをお待ちしています。 フィードバックを提供するには、「問題を送信するか、コネクタに関するヘルプを入手する」にアクセスし、フィードバックの種類を選択します。