アクションリンクの概要、認証、およびセキュリティ

Apex アクションリンクのセキュリティ、認証、表示ラベル、およびエラーについて学習します。

ワークフロー

次のフィード項目には、[参加] という 1 つの表示アクションリンクを含む 1 つのアクションリンクグループがあります。

フィード要素を使用してアクションリンクを作成および投稿するワークフローは、次のとおりです。

(省略可能) アクションリンクテンプレートを作成します。
ConnectApi.ActionLinks.createActionLinkGroupDefinition(communityId, actionLinkGroup) をコールして、少なくとも 1 つのアクションリンクを含むアクションリンクグループを定義します。
ConnectApi.ChatterFeeds.postFeedElement(communityId, feedElement) をコールしてフィード要素を投稿し、アクションリンクを関連付けます。

アクションリンクテンプレート

[設定] でアクションリンクテンプレートを作成して、共通のプロパティを持つアクションリンクグループをインスタンス化します。テンプレートをパッケージ化して他の Salesforce 組織に配布できます。

テンプレートにバインド変数を指定し、そのアクションリンクグループをインスタンス化するときに変数の値を設定します。たとえば、API バージョン番号、ユーザー ID、または OAuth トークンにバインド変数を使用します。

テンプレートでコンテキスト変数を指定することもできます。ユーザーがアクションリンクを実行すると、Salesforce によってこれらの値 (どの組織でどのユーザーがリンクを実行したかなど) が提供されます。

アクションリンクグループをインスタンス化するには、ConnectApi.ActionLinks.createActionLinkGroupDefinition(communityId, actionLinkGroup) メソッドをコールします。テンプレートで定義されたバインド変数のテンプレート ID と値を指定します。

「アクションリンクテンプレートの設計」を参照してください。

アクションリンクの種別

アクションリンクを定義するときに、actionType プロパティでアクションリンクの種別を指定します。

アクションリンクには次の 4 つの種別があります。

Api — アクションリンクは、アクション URL で同期 API をコールします。Salesforce は、サーバーから返された HTTP 状況コードに基づいて状況を SuccessfulStatus また�� FailedStatus に設定します。
ApiAsync — アクションリンクは、アクション URL で非同期 API をコールします。アクションは、非同期操作の完了時にサードパーティが /connect/action-links/actionLinkId への要求を行って状況を SuccessfulStatus または FailedStatus に設定するまで、PendingStatus 状態のままになります。
Download — アクションリンクは、アクション URL からファイルをダウンロードします。
Ui — アクションリンクはアクション URL の Web ページをユーザーに表示します。

認証

アクションリンクを定義するときは、URL (actionUrl) と、その URL に対して要求を行うために必要な HTTP ヘッダー (headers) を指定します。

外部リソースに認証が必要な場合は、リソースで必要とするすべての場所に情報を含めます。

Salesforce リソースに認証が必要な場合は、HTTP ヘッダーに OAuth 情報を含めるか、URL にベアラートークンを含めることができます。

Salesforce は自動的に次のリソースを認証します。

テンプレート内の相対 URL
アクションリンクグループが Apex からインスタンス化されるときの /services/apexrest で始まる相対 URL

機密情報を扱う操作にこれらのリソースを使用しないでください。

セキュリティ

HTTPS: アクションリンクのアクション URL は、https:// で始まるか、前の「認証」セクションのルールのいずれかに一致する相対 URL である必要があります。
暗号化: API の詳細は、暗号化して保存され、クライアントには隠匿されます。; テンプレートからインスタンス化されていないアクションリンクの actionURL、headers、および requestBody データは、組織の暗号化鍵で暗号化されます。アクションリンクテンプレートの [アクション URL]、[HTTP ヘッダー]、および [HTTP リクエストボディ] は暗号化されません。テンプレートからアクションリンクグループをインスタンス化するときに使用されるバインド値は、組織の暗号化鍵で暗号化されます。
アクションリンクテンプレート: 「アプリケーションのカスタマイズ」ユーザー権限を持つユーザーのみが、[設定] でアクションリンクテンプレートの作成、編集、削除、およびパッケージ化を行うことができます。; テンプレートに機密情報を保存しないでください。バインド変数を使用して、アクションリンクグループをインスタンス化するときに機密情報を追加します。アクションリンクグループがインスタンス化されると、値は暗号化された形式で保存されます。「アクションリンクテンプレートの設計」の「バインド変数の定義」を参照してください。
接続アプリケーション: 接続アプリケーションを使用してアクションリンクを作成する場合、常に制御可能なコンシューマー鍵のある接続アプリケーションを使用することを��勧めします。接続アプリケーションはサーバー間の通信に使用され、逆コンパイル可能なモバイルアプリケーションに対してはコンパイルされません。
有効期限: アクションリンクグループを定義するときは、有効期限 (expirationDate) を指定します。この期限後は、グループのアクションリンクを実行できなくなり、フィードから削除されます。アクションリンクグループ定義に OAuth トークンが含まれる場合、そのグループの有効期限を OAuth トークンの有効期限と同じ値に設定します。; アクションリンクテンプレートは、若干異なるユーザーの除外メカニズムを使用します。「アクションリンクテンプレートの設計」の「アクションリンクグループの有効期限の設定」を参照してください。
ユーザーの除外またはユーザーの指定: Action Link Definition Input の excludeUserId プロパティは、アクションの実行から単一ユーザーを除外する場合に使用します。; Action Link Definition Input の userId プロパティは、アクションを実行できる唯一のユーザーの ID を指定する場合に使用します。userId プロパティを指定しない場合、または null を渡す場合は、すべてのユーザーがアクションを実行できます。アクションリンクに excludeUserId と userId 両方を指定することはできません。; アクションリンクテンプレートは、若干異なるユーザーの除外メカニズムを使用します。「アクションリンクテンプレートの設計」の「アクションリンクを表示できるユーザーの設定」を参照してください。
アクションリンクグループ定義の参照、変更、または削除: アクションリンクとアクションリンクグループには、定義ビューとコンテキストユーザービューという 2 つのビューがあります。定義には、認証情報などの機密情報が含まれる可能性があります。コンテキストユーザービューは、表示オプションによって絞り込まれ、コンテキストユーザーの状態が値に反映されます。; アクションリンクグループ定義には機密情報 (OAuth トークンなど) を含めることができます。そのため、定義を参照、変更、または削除するには、ユーザーがその定義を作成したか、「すべてのデータの参照」権限を持っている必要があります。さらに、Connect REST API では、定義を作成した接続アプリケーションから要求を実行する必要があります。Apex では、定義を作成した名前空間からコールを行う必要があります。

コンテキスト変数

コンテキスト変数を使用して、アクションリンクを実行したユーザーとアクションリンクが呼び出されたコンテキストに関する情報を、アクションリンクの呼び出しによって実行された HTTP 要求に渡すことができます。コンテキスト変数は、Action Link Definition Input リクエストボディまたは ConnectApi.ActionLinkDefinitionInput オブジェクトの actionUrl、headers、および requestBody プロパティで使用できます。コンテキスト変数はまた、アクションリンクテンプレートの [アクション URL]、[HTTP リクエストボディ]、および [HTTP ヘッダー] 項目でも使用できます。テンプレートの公開後も、これらの項目は編集 (コンテキスト変数の追加と削除を含む) できます。

次のコンテキスト変数があります。

コンテキスト変数	説明
`{!actionLinkId}`	ユーザーが実行したアクションリンクの ID。
`{!actionLinkGroupId}`	ユーザーが実行したアクションリンクが含まれるアクションリンクグループの ID。
`{!communityId}`	ユーザーがアクションリンクを実行したサイトの ID。内部組織の場合、値は空のキー `"000000000000000000"` になります。
`{!communityUrl}`	ユーザーがアクションリンクを実行したサイトの URL。内部組織の場合、値は空の文字列 `""` になります。
`{!orgId}`	ユーザーがアクションリンクを実行した組織の ID。
`{!userId}`	アクションリンクを実行したユーザーの ID。

バージョン設定

API のアップグレードや機能の変更による問題を避けるため、アクションリンクを定義するときにはバージョン設定を使用することをお勧めします。たとえば、ConnectApi.ActionLinkDefinitionInput の actionUrl プロパティは https://www.example.com/api/v1/exampleResource のようになります。

テンプレートがパッケージで配布された後でも、テンプレートを使用して actionUrl、headers、または requestBody プロパティの値を変更できます。たとえば、新しい入力が必要な新しい API バージョンをリリースする場合、システム管理者は [設定] でアクションリンクテンプレートの入力を変更可能で、すでにフィード要素に関連付けられているアクションリンクでも新しい入力が使用されます。ただし、新しいバインド変数を公開済みアクションリンクテンプレートに追加することはできません。

API がバージョン管理されていない場合は、ConnectApi.ActionLinkGroupDefinitionInput の expirationDate プロパティを使用して API のアップグレードや機能変更による問題を避けることができます。「アクションリンクテンプレートの設計」の「アクションリンクグループの有効期限の設定」を参照してください。

エラー

アクションリンクの診断情報メソッド (ConnectApi.ActionLinks.getActionLinkDiagnosticInfo(communityId, actionLinkId)) を使用して、Api アクションリンクを実行後の状況コードおよびエラーを返します。診断情報は、アクションリンクにアクセスできるユーザーに対してのみ提供されます。

ローカライズされた表示ラベル

アクションリンクは、ConnectApi.ActionLinkDefinitionInput リクエストボディの labelKey プロパティおよびアクションリンクテンプレートの [表示ラベル] 項目に指定された、定義済みのローカライズされた表示ラベルセットを使用します。

表示ラベルのリストについては、「アクションリンクの表示ラベル」を参照してください。

アクションリンクに適した表示ラベルキー値がない場合、アクションリンクテンプレートの [表示ラベル] 項目にカスタムラベルを指定し、[表示ラベルキー] を [なし] に設定します。ただし、カスタム表示ラベルはローカライズされません。

メモ

Apex 開発者ガイド