接続の確立

NetSuite への接続

NetSuite は現在、2つの異なるAPI を提供しています。

SuiteTalk はNetSuite との通信に使用する、SOAP ベースのより古いサービスです。多くのエンティティを幅広くサポートし、INSERT / UPDATE / DELETE を完全にサポートします。しかしデータの抽出用ツールは低機能で、SELECT 時のパフォーマンスは極めて低いです。テーブルを結合するよい方法もありません。データのグループ化および集計はこのAPI からは利用できず、そのためこれらの操作をサポートするには、すべてをクライアントサイドで実行しなければなりません。
SuiteQL は新しいAPI です。サービスとのSQL ライクな通信方法を実現するため、JOIN の機能はより豊富になり、GROUP BY や集計機能もサポートします。加えて、抽出したいカラムだけを取得する機能も完全にサポートします。そのため、データを抽出する際のパフォーマンスがSuiteTalk より大幅に向上しています。ただし、サポートされるのはデータの抽出のみです。

NetSuite に接続するには、以下を行う必要があります。

Schema を設定して、接続に使用するAPI を指定。
データを取得するだけの場合は、SuiteQL の使用をお勧めします。データの取得および変更が必要な場合は、SuiteTalk の使用をお勧めします。
使用するAPI に適した接続オプションを設定します。（それぞれのAPI で、許可の設定で説明するように、利用可能な接続オプションが異なることに注意してください。）
SuiteTalk に接続する場合は、NetsuiteMetadataFolder を指定することをお勧めします。 NetSuite Metadata Folder は、NetSuite のメタデータファイルが格納されるフォルダです。指定しない場合は、フォルダの場所は自動的に選択されます。テーブルに関するメタデータをリスト化する際のロード時間を速くするには、このプロパティを設定してください。
接続するすべてのユーザーが、NetSuite Web サービス経由で接続するためのAccountId 上の権限を持っていることを確認してください。必須およびオプションの権限について詳しくは、許可の設定を参照してください。

Web サービス権限用のロールを作成または編集するには：
1. NetSuite にログインします。
2. 新しいロールを作成する必要がある場合は、［セットアップ］->［ユーザーとロール］->［ロールの管理］->［New］の順に進みます。
  既存のロールを変更する必要がある場合は、［セットアップ］->［ユーザーとロール］->［ロールの管理］に移動して、変更するロールを選択します。
3. ［アクセス許可］->［セットアップ］をクリックします。
4. SOAP Web サービスとREST Web サービスの権限を追加します。
5. その他、さまざまなエンティティやトランザクションを扱うために必要な権限を追加します。（許可の設定を参照してください。）
6. ［設定］メニューから［ユーザーとロール］->［ユーザー管理］に移動します。作成したユーザーまたは変更したユーザを選択します。
7. ［アクセス］タブで、新しく作成したロールを追加します。
8. 新しいユーザーまたは変更されたユーザーを保存します。

NetSuite への認証

このセクションでは、SuiteTalk の初期のバージョン（Basic 認証を使用）、SuiteTalk の以降のバージョン、およびSuiteQL のすべてのバージョンからNetSuite に認証する方法について説明します。

SuiteTalk 2020.2 以前のバージョン

2020.2現在、NetSuite はBasic（ユーザーネーム / パスワード）認証をサポートしていません。Version が2020.2以下の値に設定されている場合、CData ADO.NET Provider for NetSuite はユーザーネームとパスワードでの接続を引き続きサポートしますが、すべてのお客様が次に記載のOAuth とトークンベース認証システムに移行することを推奨します。

SuiteTalk の初期バージョンで引き続きBasic 認証を使用するには、AuthScheme をBasic に設定して、ユーザー / パスワード資格情報をサポートします。ただし、これを使用するにはVersion に過去のバージョンを手動で指定する必要があります。

トークンベースまたはOAuth 2.0 認証のいずれかをサポートするには、AuthScheme をOAuth に設定します。

SuiteTalk またはSuiteQL

NetSuite は2つの形式のOAuth 認証を提供します。

トークンベース認証（TBA）は、基本的にOAuth 1.0 で、OAuthAccessToken とOAuthAccessTokenSecret を実行時ではなくNetSuite UI 内で作成します。 TBA は、2020.2 以降のSuiteTalk およびSuiteQL の両方で利用可能です。
OAuth 2.0 認証は、SuiteQL でのみ利用できます。OAuth 2.0 認証を強制するには、次のいずれかを実行します。
- OAuthVersion を使用するAPI に明示的に設定、または
- Schema をSuiteQL に設定

Note： SuiteTalk を使用している場合、OAuthVersion を SuiteTalk に設定しても、OAuth 2.0 は使用できないことに注意してください。SuiteTalk はOAuth 2.0 をサポートしません。

トークンベースまたはOAuth 2.0 認証のいずれかをサポートするには、AuthScheme をOAuth に設定します。

トークンベース認証（OAuth 1.0）

トークンベース認証（TBA）は基本的にOAuth 1.0 です。TBA は、SuiteTalk およびSuiteQL Schema のどちらでも使用可能です。

トークンベース認証は、権限を持った管理者がOAuthClientId、OAuthClientSecret、 OAuthAccessToken、およびOAuthAccessTokenSecret をNetSuite UI 内で直接作成することで実行されます。

TBA の使用をサポートするには、AuthScheme をToken に設定し、以下で説明するようにNetSuite UI でトークンを作成します。

NetSuite UI でのトークンの作成

多くのNetSuite 管理者は、NetSuite UI で直接トークンを作成して割り当てることを好みます。トークン経由で接続することで、ユーザーはOAuth アクセストークンを生成するための通常の手順をスキップできます。これにより、管理者はアクセス権の付与をより直接的に制御できるようになりますが、新しいトークンを作成する必要があるたびに、常にUI で手動の手順を実行する必要があります。

NetSuite UI で直接トークンを作成して割り当てる代わりに、次の手順に従ってください。

NetSuite で、管理者権限を持つアカウントを使用してログインします。
［セットアップ］->［会社］->［機能の有効化］->［SuiteCloud］->［認証の管理］の順に進みます。
トークンベース認証およびTBA：認可フローを選択します。
変更を保存します。
［セットアップ］->［統合］->［統合の管理］の順に進みます。
新しい統合を作成して、［トークンベース認証］を選択します。
統合が作成されると、Cunsumer Key とConsumer Secret が表示されます。これらは、直接OAuthClientId とOAuthClientSecret 接続プロパティにマップされます。
Cunsumer Key およびConsumer Secret の値を記録します。
新しいロールを作成するか、既存のロールを編集するには、［セットアップ］->［ユーザーとロール］->［ロールの管理］の順に進みます。
［アクセス許可］->［セットアップ］に移動します。
ロールに次の権限を割り当てます。User Access Token: Full、Access Token Management: Full、 Web Servies: Full。
［リスト］->［従業員］->［従業員］にリストされているユーザーに新しいロールを追加するには、従業員を選択し、 ［アクセス］->［ロール］に移動します。
［セットアップ］->［ユーザーとロール］->［アクセストークン］の順に進み、新しいアクセストークンを作成します。
アプリケーション名には、先ほど作成した統合を指定します。これを、前のステップで作成または更新したのと同じユーザーとロールに割り当てます。
アクセストークンを作成すると、Token Id とToken Secret が表示されます。これらは、直接OAuthAccessToken とOAuthAccessTokenSecret にマップされます。これらを書き留めます。

アクセストークンが作成されたら、前の手順で取得した値を使用して接続することができます。接続する前に、少なくとも次の接続プロパティを指定します。

AccountId = 接続するアカウント。
OAuthClientId = アプリケーションの作成時に表示されるConsumer Key。
OAuthClientSecret = アプリケーションの作成時に表示されるConsumer Secret。
OAuthAccessToken = アクセストークンが作成されたときのToken Id。
OAuthAccessTokenSecret = アクセストークンが作成されたときのToken Secret。

OAuth 2.0

NetSuite SuiteTalk は、OAuth 2.0 認証をサポートしています。すべてのOAuth フローで、この認証を有効にするにはAuthScheme をOAuth に設定する必要があります。Web アプリケーション経由で認証したい場合は、カスタムOAuth アプリケーションの作成で説明するようにカスタムOAuth アプリケーションを作成する必要があります。

以下のサブセクションでは、3つの標準的な認証フローでのNetSuite への認証について詳しく説明します。

デスクトップ：ユーザーのローカルマシン上でのサーバーへの接続で、テストやプロトタイピングによく使用されます。組み込みOAuth またはカスタムOAuth で認証されます。
Web：共有ウェブサイト経由でデータにアクセスします。カスタムOAuth でのみ認証されます。
ヘッドレスサーバー：他のコンピュータやそのユーザーにサービスを提供する専用コンピュータで、モニタやキーボードなしで動作するように構成されています。組み込みOAuth またはカスタムOAuth で認証されます。

カスタムOAuth アプリケーションの作成方法と、組み込みOAuth 認証情報を持つ認証フローでもカスタムOAuth アプリケーションを作成したほうがよい場合の説明については、カスタムOAuth アプリケーションの作成を参照してください。

NetSuite で利用可能な接続文字列プロパティの全リストは、Connection を参照してください。

デスクトップアプリケーション

CData は、デスクトップでの認証を簡単にする組み込みOAuth アプリケーションを提供します。例えば、ユーザーがインターネットに接続されていないローカルサーバーを使用しているような場合に利用できます。

また、NetSuite コンソールで設定および登録するカスタムOAuth アプリケーションを介してデスクトップから認証することもできます。詳しくは、カスタムOAuth アプリケーションの作成を参照してください。

接続の前に、以下の変数を設定します。

InitiateOAuth = GETANDREFRESH。OAuthAccessToken を自動的に取得およびリフレッシュするために使用します。
カスタムOAuth アプリケーションのみ：
- OAuthClientId = カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret = カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。
- CallbackURL = カスタムOAuth アプリケーションの登録時に定義されたリダイレクトURI。

接続すると、本製品はデフォルトブラウザでNetSuite のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。

アプリケーションにアクセス許可を与えると、本製品はOAuth プロセスを完了します。

本製品はNetSuite からアクセストークンを取得し、それを使ってデータをリクエストします。
OAuth 値はOAuthSettingsLocation で指定されたパスに保存されます。これらの値は接続間で永続化されます。

アクセストークンの期限が切れたときは、本製品は自動でアクセストークンをリフレッシュします。

Web アプリケーション

Web 経由で認証する場合は、カスタムOAuth アプリケーションの作成で説明するようにNetSuite にカスタムOAuth アプリケーションを作成および登録する必要があります。それから本製品を使用してOAuth トークンの値を取得および管理します。

このセクションでは、OAuth アクセストークンの取得方法、ドライバーにOAuth アクセストークンを自動的に更新させる方法、OAuth アクセストークンを手動で更新する方法について説明します。

OAuth アクセストークンの取得：

次の接続プロパティを設定し、OAuthAccessToken を取得します。
- OAuthClientId = アプリケーション設定のクライアントId。
- OAuthClientSecret = アプリケーション設定のクライアントシークレット。
ストアドプロシージャを呼び出し、OAuth 交換を完了します。
- GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、CallbackURL をアプリケーション設定で指定したリダイレクトURI に設定します。ストアドプロシージャは、OAuth エンドポイントへのURL を返します。
- ステップ1でストアドプロシージャが返したURL に移動します。ログインしてWeb アプリケーションを認可します。コールバックURL にリダイレクトされます。
- GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、リダイレクトURI のクエリ文字列のcode パラメータに設定します。

アクセストークンとリフレッシュトークンを取得したのち、データに接続してOAuth アクセストークンを自動的にリフレッシュできます。

OAuth アクセストークンの自動リフレッシュ：

本製品がOAuth アクセストークンを自動的にリフレッシュするようにするには、次のように設定します。

はじめてデータに接続する際、次の接続プロパティを設定します。
- InitiateOAuth = REFRESH。
- OAuthClientId = アプリケーション設定のクライアントId。
- OAuthClientSecret = アプリケーション設定のクライアントシークレット。
- OAuthAccessToken = GetOAuthAccessToken によって返されたアクセストークン。
- OAuthSettingsLocation = 本製品がOAuth 値を保存する場所のパス。これは接続間で維持されます。
その後のデータ接続では、以下を設定します。
- InitiateOAuth
- OAuthSettingsLocation

OAuth アクセストークンの手動リフレッシュ：

OAuth アクセストークンを手動でリフレッシュするために必要な唯一の値は、OAuth リフレッシュトークンです。

ExpiresIn 期間（GetOAuthAccessToken が返す）が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
次の接続プロパティを設定します。
- OAuthClientId = アプリケーション設定のクライアントId。
- OAuthClientSecret = アプリケーション設定のクライアントシークレット。
RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。Open は、新規接続を開きます。

OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

ヘッドレスマシン

ヘッドレスマシンに置かれているリソースにログインする必要がある場合は、インターネットブラウザに対応した別の端末で認証する必要があります。以下のいずれかの方法で行います。

オプション1：OAuthVerifier 値を取得します。
オプション2：インターネットブラウザに対応したマシンに本製品をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

オプション1またはオプション2を実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするようにドライバーを設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。以下の手順に従います。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得します。

埋め込みOAuth アプリケーションを使用する場合は、GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。

カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定します。
- InitiateOAuth = OFF。
- OAuthClientId = アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret = アプリケーションの登録時に割り当てられたクライアントシークレット。
GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャは、カスタムOAuth アプリケーションが登録されたときに構築されたCallbackURL を返します。（カスタムOAuth アプリケーションの作成を参照してください。）

このURL をコピーして、新しいブラウザのタブに貼り付けます。
ログインして、本製品にアクセス許可を与えます。OAuth アプリケーションは、code というパラメータを付加したリダイレクトURI にリダイレクトします。このパラメータの値を控えておきます。OAuthVerifier 接続プロパティを設定するために、後で必要になります。
OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換します。ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。
- InitiateOAuth = REFRESH。
- OAuthVerifier = 控えておいたverifier code（リダイレクトURI のcode パラメータの値）。
- OAuthSettingsLocation = 暗号化されたOAuth 認証値を指定されたファイルに永続化。
- カスタムOAuth アプリケーションのみ：
  - OAuthClientId = カスタムOAuth アプリケーション設定のクライアントId。
  - OAuthClientSecret = カスタムOAuth アプリケーション設定のクライアントシークレット。
接続をテストしてOAuth 設定ファイルを生成します。
次のプロパティを再設定して、接続してください。
- InitiateOAuth = REFRESH。
- OAuthSettingsLocation = 暗号化されたOAuth 認証値を含むファイル。アクセストークンの自動リフレッシュを有効にするには、このファイルが本製品に読み書きのアクセス許可を与えることを確認してください。
- カスタムOAuth アプリケーションのみ：
  - OAuthClientId = アプリケーションの登録時に割り当てられたクライアントId。
  - OAuthClientSecret = アプリケーションの登録時に割り当てられたクライアントシークレット。

オプション2：OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続をインストールし、作成する必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定されたパスに暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンでデータに接続するには、次の接続プロパティを設定します。

InitiateOAuth = REFRESH
OAuthSettingsLocation = ブラウザでマシンからコピーしたOAuth 設定ファイルへのパス。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品に読み書きのアクセス許可を与えることを確認してください。
カスタムOAuth アプリケーションのみ：
- OAuthClientId = カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret = カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。

同時リクエスト

NetSuite はアカウント毎に一定数の同時リクエストのみ受け付け、接続毎に設定できます。（デフォルトは通常5です。）同時リクエストの最大数がすでに使用されているときに別のリクエストが行われた場合、ユーザーは"Only one request may be made against a session at a time" エラーを受け取ることがあります。

CData ADO.NET Provider for NetSuite は、同時リクエスト制限を超えないように追加のリクエストを遅延させることで、この状況に対処しようとします。ただし、アカウントに複数のマシンやアプリケーションから接続がある場合、この処理を適切に実行することができないことがあります。

非同期サービス

NetSuite の応答時間の遅延は、INSERT、更新、または削除にも及びます。これはバッチ処理を使用する場合に特に顕著です。一度に複数のレコードを挿入、更新、または削除する場合は、UseAsyncServices をtrue に設定するとよいかもしれません。これによりリクエストはNetSuite 側で非同期で処理され、JobId がInfo#TEMP テーブルに返されます。 JobId はストアドプロシージャCheckJobStatus およびGetJobResults に対して、ジョブがいつ完了したか、エラーが発生したかどうか、新規作成されたエンティティのInternalId を確認できます。