Salesforce Connect (OData 4.0) で Oiyokan を利用する際のポイント

この記事では、`Salesforce` から OData 4.0 としての `Oiyokan` に接続するときのポイントを紹介します。なお、[Oiyokan そのものの説明については、こちらの記事を参照ください](https://qiita.com/igapyon/items/3fbdb0f3d3520a54f2a9)

![20210504-02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/8fa935c8-9529-a3cf-75f4-bd475369eb8f.png)

## Salesforce から利用可能な OData v4 情報
Salesforce Connect から接続可能な OData v4 として構成するにはいくつか満たしておくべき条件があります。

### データ構造の制約

- Entity には Keyが必要です
    - つまり、テーブルには基本的に Primary Key が必要です
    - OData v4 仕様としても Entity には Key が要求されます
    - Key がない場合、Salesforce が $metadata を読み込む際にエラーが発生します (その場合、親切ではないエラーメッセージが表示される可能性があります)

### サポート型マッピング

現時点での Salesforce から利用可能な Oiyokan のサポート型マッピングは以下の通りです。

| Edm 型             | JDBC 型        | (参考) h2 型 |
| ------             | ---            | ---         |
| Edm.SByte          | Types.TINYINT  | TINYINT     |
| Edm.Int16          | Types.SMALLINT | SMALLINT    |
| Edm.Int32          | Types.INTEGER  | INTEGER     |
| Edm.Int64          | Types.BIGINT   | BIGINT      |
| Edm.Decimal        | Types.DECIMAL  | DECIMAL     |
| Edm.String         | Types.CHAR     | CHAR        |
| Edm.String         | Types.VARCHAR  | VARCHAR     |
| Edm.String         | Types.CLOB     | CLOB        |
| Edm.Boolean        | Types.BOOLEAN  | BOOLEAN     |
| Edm.Single         | Types.REAL     | REAL        |
| Edm.Double         | Types.DOUBLE   | DOUBLE      |
| Edm.Date           | Types.DATE     | DATE        |
| Edm.DateTimeOffset | Types.TIMESTAMP | TIMESTAMP  |
| Edm.Binary | Types.VARBINARY        | VARBINARY   |
| Edm.Binary | Types.BLOB             | BLOB        |

- Edm.TimeOfDay は Salesforce がサポートしません。無理に利用しようとすると不親切なエラーが発生する可能性があります。
- Edm.Guid は現時点では Oiyokan がサポートしないため利用できません。(Oiyokan の仕様に由来する利用不可です。JSON設定ファイルを直接編集して Binary にマップすると読み込みは可能になります)
- Oiyokan の Edm と JDBC Types との[詳細なマッピング情報はこちらの記事を参照](https://qiita.com/igapyon/items/8a46f5a2ba67f13a7d68)。

### Salesforce OData 4.0 向け Oiyokan 推奨設定

- Oiyokan Initializr の `$filter: Treat null as blank` にチェックを入れて、文字列を NULLで検索する場合に長さ0の文字列も検索結果に含めるようにします。
    - これにより、Salesforce がブランク文字列を null として検索する仕様に一部対応することができるようになります
    - 仮にこれを指定しない場合、RDB上のブランク文字列を条件にした検索に Salesforce の標準画面や Apex などからの検索でヒットできません

![20210504-08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/914a5375-13a1-1fcb-8d02-d882a777f774.png)

## `Trailhead` `Playground` からの設定例

ここからは `Trailhead` `Playground` からの設定例の手順を示します。

### あらかじめ Heroku 上に Oiyokan をデプロイされている前提で記述されています

これ以降の手順は、Heroku に Oiyokan がデプロイ済みで、以下の URL により OData v4 アクセス可能な状態になっている前提で記載します。

- [https://oiyokan.herokuapp.com/odata4.svc/](https://oiyokan.herokuapp.com/odata4.svc/)

> Note: この URL は記事執筆時点 (2021-05-16) では読み書き可能ですが、将来的には書き込みできなくなる可能性があります。

### 「設定」から「外部データソース」を開き、「新規外部データソース」をクリックします

![20210504-01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/8249f5cc-0a5b-2454-4eeb-be85ead6a7fc.png)

### 「外部データソースの編集」にて、OData v4 URL などを記入します

- 「外部データソースの編集」にて、OData v4 URL などを記入します
- 「種別」は「Salesforce Connect: OData 4.0」を選びます
- URL には OData v4 として利用可能な Oiyokan の URL を記入します
- 「書き込み可能外部オブジェクト」をチェックします
- 記入が終わったら「保存」をクリックします

![20210504-02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/8fa935c8-9529-a3cf-75f4-bd475369eb8f.png)

### 「検証して同期」をクリックします

「検証して同期」をクリックして設定の正しさを検証して同期します。

![20210504-03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/cc806527-e871-d6df-83c6-72eb33db64f7.png)

### テーブル名を選択して同期します

「検証して同期」が成功するとテーブル名が一覧表示されます。利用したい「テーブル名」のチェックボックスをONにして「同期」をクリックします。

![20210504-04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/bf51a7a0-b951-849e-fe7c-6c4dd5f98fcf.png)

### 外部オブジェクトを「検証」します

テーブルの同期が成功すると外部オブジェクト一覧に追加表示されます。「検証」をクリックして確認します。

![20210504-05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/92826a10-c362-9309-1a4b-5f0bbe790da1.png)

### 「クエリの実行」をクリックして検証を実施します

「クエリの実行」をクリックして検証を実施します。「成功したクエリ」に表示されることを確認します。

![20210504-06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/3122f3f2-c17e-a3cc-ed0c-94cd170ef8d9.png)

> - Note: RDBの設定によっては、ソート順が Salesforce の期待するものと一致しない場合があります。この差異が出るのは Oiyokan としての仕様です。

### 外部オブジェクトにアクセスします

追加された外部オブジェクトには Salesforce 標準機能や Apex などからアクセス可能になります。

![20210504-07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/105739/f4902937-8e3c-e0de-89fc-952068b6eb4a.png)

### 外部オブジェクトへの変更は、非同期での実行となります

* Salesforce から外部オブジェクトへの INSERT/UPDATE/DELETE は非同期(async)操作となります。
* Apexからのアクセスの場合は、async 系のメソッドの利用が必要です。

> * 初出: 2021-05-16