この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

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

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

Workflow

次のフィード項目には、[承認] および [却下] という 2 つのアクションリンクを含む 1 つのアクションリンクグループがあります。フィード項目の [承認] および [却下] アクションリンク

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

(省略可能) アクションリンクテンプレートを作成します。
/connect/action-link-group-definitions に対して要求を実行して、アクションリンクグループを定義するか、テンプレートからアクションリンクグループをインスタンス化します。アクションリンクグループには、少なくとも 1 つのアクションリンクが含まれます。
/chatter/feed-elements に対して要求を実行して、フィード要素を投稿し、アクションリンクを関連付けます。

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

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

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

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

アクションリンクグループをインスタンス化するには、/connect/action-link-group-definitions リソースへの要求を実行します。テンプレートで定義されたバインド変数のテンプレート 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 ページをユーザに表示します。

さまざまな種別のアクションリンクのさまざまなワークフローで、アクションリンクの状況 (Pending、Successful、または Failed) が設定されます。詳細は、/connect/action-links/actionLinkIdを参照してください。

認証

アクションリンクを定義するときは、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 トークンなど) を含めることができます。そのため、定義を参照、変更、または削除するには、ユーザがその定義を作成したか、「すべてのデータの参照」権限を持っている必要があります。さらに、Chatter 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 のアップグレードや機能の変更による問題を避けるため、アクションリンクを定義するときにはバージョン設定を使用することをお勧めします。たとえば、Action Link Definition Input の actionUrl プロパティは https://www.example.com/api/v1/exampleResource のようになります。

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

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

エラー

アクションリンクの診断情報リソース (/connect/action-links/actionLinkId/diagnostic-info) を使用して、Api アクションリンクおよび AsyncApi アクションリンクを実行後の状況コードおよびエラーを返します。診断情報は、アクションリンクにアクセスできるユーザに対してのみ提供されます。

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

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

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

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

メモ

Chatter REST API 開発者ガイド