外部システムからSalesforceのREST API を使用する

# 外部システムからSalesforceのREST API を使用してみる
接続アプリケーションの作成から標準REST APIをコールするまで。
Apex REST Webサービスおよび Apex REST コールアウトはここでは扱いません。

## 1. インテグレーション用ユーザの作成
REST APIを使用するためにはまず、インテグレーション用ユーザを作成する必要があります。
外部システムからSalesforceのREST APIを使用する際は、まずインテグレーション用ユーザにログインする必要があります。
外部システムはインテグレーション用ユーザの権限、共有設定によって制限を受けます。

1. インテグレーション用にユーザとプロファイルを作成します。
2. インテグレーション用プロファイルでシステム管理者権限の「API の有効化」が有効になっているのを確認します。
![RESTAPI001.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/2263f4bf-3e2d-9ded-07e2-c9c1bd69866d.png)

#### 参考
* [実装に関する考慮事項 | SOAP API 開発者ガイド](https://developer.salesforce.com/docs/atlas.ja-jp.224.0.api.meta/api/implementation_considerations.htm?SearchType=Stem)


## 2. 接続アプリケーションを作成する(OAuthによる認証)
1. [設定] - [アプリケーション] - [アプリケーションマネージャ][^2] から[新規接続アプリケーション]をクリックします。
2. 必要事項を入力します。
3. [OAuth 設定の有効化]にチェックを入れ、コールバックURLとOAuthの範囲を指定します(OAuthの範囲については[こちら](https://help.salesforce.com/articleView?id=remoteaccess_oauth_tokens_scopes.htm&type=5)を参照)。
![RESTAPI002_2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/fb524fa0-bd40-a88d-280b-fd9280e9fedc.png)
4. 保存すると、接続アプリケーションの定義の詳細ページが表示されます。ここのコンシューマ鍵とコンシューマの秘密は認証を行う際に必要になります。(このページは [設定] - [オブジェクトマネージャ] から対象の接続アプリケーションの▼ボタンから[参照]をクリックすることで表示できます)
![RESTAPI003_2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/1ca052c4-4e20-78e6-ea0f-c853cdd22051.png)
5. [Manage]ボタンをクリックすると、接続アプリケーションのポリシーの詳細ページが表示されます。この画面で接続アプリケーションのOAuthアクセスポリシーを管理します。([設定] - [アプリケーション] - [接続アプリケーション] - [接続アプリケーションを管理する] からもアクセス可能です)
![RESTAPI011.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/7d41ed6f-ca32-c250-6602-1570db295680.png)


* IP制限の緩和
    * IP制限を適用: ユーザプロファイルに設定されたIP制限が適用されます。
    * IP制限を適用し、更新トークンを緩和: 更新トークを使用してアクセストークンを取得する場合、IP制限が適用されません。
    * 有効化したデバイスのIP制限を緩和: アプリケーションを実行しているユーザは、次のいずれかの条件を満たす場合に、組織の IP 制限をスキップできます。
        * アプリケーションに IP 範囲のホワイトリストが存在し、アプリケーションが Web サーバの認証フローを使用している場合。ホワイトリストに登録された IP からの要求のみが許可されます。
        * アプリケーションに IP 範囲のホワイトリストがなく、アプリケーションが Web サーバの認証フローを使用していて、ユーザが新しいブラウザまたはデバイスから Salesforce にアクセスした場合に ID 確認を正常に完了している場合。
    * IP制限を緩和: ユーザプロファイルに設定されたIP制限は適用されずにアプリケーションを実行できます。
* 許可されているユーザ
    * すべてのユーザは自己承認可能: すべてのユーザがアプリケーションを実行できます。アプリケーションの初回実行時にアプリケーションを承認する画面がユーザに表示されます。
    * 管理者が承認したユーザは事前承認済み: 関連付けられたプロファイルと権限セットが適用されているユーザのみがアプリケーションを実行できます(ただし、ユーザが「任意の API クライアントを使用」権限を持っている場合は実行可能です)。
* シングルログアウトを有効化
    * チェックがついている時、ユーザがSalesforceからログアウトすると接続アプリケーションからも自動ログアウトします(ログアウトリクエストを送信するURLの設定が必要です)。
* カスタム接続アプリケーションハンドラ
    * Apexを使用してカスタムのポリシーを設定することができます。

#### 参考
* [接続アプリケーションの基本設定 | コードを使用したSALESFORCEの拡張](https://help.salesforce.com/articleView?id=connected_app_create_basics.htm&type=5)
* [API インテグレーション用の OAuth 設定の有効化 | コードを使用したSALESFORCEの拡張](https://help.salesforce.com/articleView?id=connected_app_create_api_integration.htm&type=5)
* [OAuth トークンおよび範囲 | コードを使用したSALESFORCEの拡張](https://help.salesforce.com/articleView?id=remoteaccess_oauth_tokens_scopes.htm&type=5)
* [クイックスタート | REST API 開発者ガイド](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/quickstart.htm)
* [接続アプリケーションの OAuth アクセスポリシーの管理 | Salesforceヘルプ](https://help.salesforce.com/articleView?id=connected_app_manage_oauth.htm&type=5)
* [カスタム接続アプリケーションハンドラを介したアクセスの管理 | Salesforceヘルプ](https://help.salesforce.com/articleView?id=connected_app_manage_custom_handler.htm&type=5)

## 3. 外部システムで認証を行う
Salesforceで使用できる認証フローは下記の公式ヘルプ記事に記載されています。
[OAuth 認証フロー](https://help.salesforce.com/articleView?id=remoteaccess_oauth_flows.htm&type=5)

ここでは「ユーザ名パスワード OAuth 認証フロー」について扱っていきたいと思います
(追記20201019 __このフローはログイン情報をやり取りするため[非推奨](https://help.salesforce.com/articleView?id=remoteaccess_oauth_username_password_flow.htm&type=5)です。__対話形式のログインを使用しない場合は[「OAuth 2.0 JWT ベアラーフロー」](https://help.salesforce.com/articleView?id=remoteaccess_oauth_jwt_flow.htm&type=5)を使用します)。
また、ここからは外部システムのシュミレーションとして、Chromeの拡張機能である「[Talend API Tester](https://chrome.google.com/webstore/detail/talend-api-tester-free-ed/aejoelaoggembcahagimdiliamlcdmfm)」を使っていきます。

### セキュリティトークンの取得
ユーザ名パスワード OAuth 認証フロー ではセキュリティトークンが必要なので、用意します。

1. インテグレーションユーサでログインし、[右上のユーザアイコン] - [設定] - [私の個人情報] - [私のセキュリティトークンのリセット][^1] の[セキュリティトークンのリセット]をクリックします。※[セキュリティトークンのリセット]が表示されない場合、セキュリティトークンの取得は必要ありません。
![RESTAPI004.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/71b20bc7-a7db-a754-d50d-bf7e8ab0b6e5.png)
2. インテグレーション用ユーザに設定しているメールアドレスにセキュリティトークンが記載されたメールが届きます。

<!-- ※私のセキュリティトークンのリセットが表示されない場合は[こちら](https://help.salesforce.com/articleView?id=000331668&language=ja&type=1&mode=1)を参照。 -->

### ユーザ名パスワード OAuth 認証
1. Talend API Tester を実行します。
2. リクエストを新規で作成し、下記のように設定を行います。
    * METHOD: POST
    * パス: 適切なSalesforce トークン要求エンドポイント(例: `https://login.salesforce.com/services/oauth2/token`)
    * HEADERS
        * Content-Type: `application/x-www-form-urlencoded`
3. BODYにFormを選択し、次のパラメータを設定します。
    * grant_type=password
    * client_id=[接続アプリケーションのコンシューマ鍵]
    * client_secret=[接続アプリケーションのコンシューマの秘密]
    * username=[インテグレーション用ユーザのSalesforceユーザ名]
    * password=[インテグレーション用ユーザのSalesforceログインパスワード+セキュリティトークン]
![RESTAPI005_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/0c3a3539-aec0-9fab-f3b0-40a41f524e5e.png)
4. Sendボタンを押すと、認証結果が返されます。RESTリクエストを送信するときにレスポンスボディのaccess_tokenを使用します。
![RESTAPI006_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/f38d14b0-baf5-e369-f79e-2ade4d711119.png)

#### 参考
* [認証について | REST API 開発者ガイド](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/intro_understanding_authentication.htm)
* [ユーザ名パスワード OAuth 認証フローについて | REST API 開発者ガイド](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/intro_understanding_username_password_oauth_flow.htm)

## 4. REST API リソースを使ったHTTPリクエストの送信
Salesforce の REST API でサポートされている REST リソースの一覧は[こちら](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/resources_list.htm)から確認できます。
使用例をいくつか記します。

### オブジェクトのメタデータを取得する
指定したオブジェクトの項目、子リレーションなどのメタデータを取得します。
RESTリソースは[sObject Describe](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/resources_sobject_describe.htm) を使用します。

1. Talend API Tester を実行します。
2. リクエストを新規で作成し、下記のように設定を行います。
    * METHOD: GET (使用するHTTPメソッドは[公式のリファレンス](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/resources_sobject_describe.htm))に記載されています。)
    * パス: `http://[カスタムドメイン]/services/data/[APIバージョン]/sobjects/[オブジェクトのAPI参照名]/describe`
    * HEADERS
        * Authorization: `Bearer [認証のレスポンスのaccess_tokenの値]` <font color="Red">※注意:Bearerとトークンの間に半角スペースが必要</font>
![RESTAPI007_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/5d267cfb-f45c-0753-88e7-2ca9493d114e.png)
3. Sendボタンを押すと、オブジェクトのメタデータが返されます。
![RESTAPI008.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/fd729aaf-f29e-f6e1-ddb0-f93e125ccb5f.png)

例で使用したパス: `/services/data/v36.0/sobjects/Account/describe`

### SOQLクエリを実行する
クエリ結果を取得します。
RESTリソースは[Query](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/resources_query.htm) を使用します。

1. Talend API Tester を実行します。
2. リクエストを新規で作成し、下記のように設定を行います。
    * METHOD: GET
    * パス: `http://[カスタムドメイン]/services/data/[APIバージョン]/query/?q=[SOQLクエリ]` <font color="Red">※注意:クエリの半角スペースは「+」に置き換えが必要</font>
    * HEADERS
        * Authorization: `Bearer [認証のレスポンスのaccess_tokenの値]` <font color="Red">※注意:Bearerとトークンの間に半角スペースが必要</font>
![RESTAPI009_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/c7ff3586-9c18-1f7e-0211-1346aabb46fd.png)
3. Sendボタンを押すと、クエリ結果が返されます。
![RESTAPI010.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/125621/b2b52ff1-7175-70b4-c5fc-d136c0545568.png)


例で使用したパス: `/services/data/v36.0/query/?q=SELECT+Id,+Name+FROM+Account`

### その他の例
REST API 開発者ガイドにはREST APIの例が書かれています。

* [レコードの作成](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/dome_sobject_create.htm)
* [レコードの更新](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/dome_update_fields.htm)
* [レコードの削除](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/dome_delete_record.htm)

### 参考
* [ステップ 3: cURL で HTTP 要求を送信する | REST API 開発者ガイド](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/intro_usage_rest_resources.htm)
* [リファレンス | REST API 開発者ガイド](https://developer.salesforce.com/docs/atlas.ja-jp.api_rest.meta/api_rest/resources_list.htm)


<!-- 注釈 -->
[^1]: Classic → [右上のユーザ氏名] - [私の設定] - [個人用] - [私のセキュリティトークンのリセット]
[^2]: Classic → [設定] - [ビルド] - [作成] - [アプリケーション] の接続アプリケーションのセクションから新規ボタンをクリック