接続の確立

コネクタ内で利用可能なオブジェクトは、"cdata.netsuite" モジュールからアクセスできます。モジュールのオブジェクトを直接使用するには：

モジュールを以下のようにインポートします。
```
import cdata.netsuite as mod
```

接続を確立するには、以下のような適切な接続文字列を使用してコネクタオブジェクトからconnect() メソッドを呼び出します。

mod.connect("AccountId=XABC123456;Schema=SuiteTalk;AuthScheme=Token;OAuthClientId=MyOAuthClientId;OAuthClientSecret=MyOAuthClientSecret;OAuthAccessToken=MyOAuthAccessToken;OAuthAccessTokenSecret=MyOAuthAccessTokenSecret;")

接続の前に

接続するには、特定の権限が割り当てられたロールがユーザーに付与されている必要があります。

ユーザーロールを作成または編集するには：

NetSuite にログインします。
新しいロールを作成するには、NetSuite のナビゲーションメニューで設定 -> ユーザー / ロール -> ロール管理にマウスを合わせ、新規作成をクリックします。

または

既存のロールを編集するには、NetSuite ナビゲーションメニューで設定 -> ユーザー / ロール にマウスを合わせ、ロール管理をクリックします。ロール管理ページが開きます。

ロール管理ページで、「名前」列に編集したいロールがある行で、「編集」列のカスタマイズをクリックします。

どちらの操作でもロールページが開きます。
許可セクションで、設定 () ドロップダウンメニューをクリックします。
設定 () メニューで、追加ボタンの上にあるドロップダウンメニューをクリックします。
SOAP Web サービスの権限を選択し、追加をクリックします。同様にREST Web サービスの権限も追加します。
必要に応じて他の権限も選択します。すべての権限とその用途、必要な場面については許可の設定を参照してください。
NetSuite ナビゲーションメニューで設定、次にユーザー / ロール にマウスを合わせ、ロール管理をクリックします。ロール管理ページが開きます。
「名前」列で、作成または編集したロールを割り当てたいユーザーの名前をクリックします。従業員ページが開きます。
従業員ページのタブバーでアクセスタブをクリックし、編集をクリックします。編集モードの従業員ページが開きます。
ページ下部の追加ボタンの上にあるドロップダウンメニューから、新しい（または編集した）ロールを選択し、追加をクリックします。
保存をクリックします。

NetSuite への接続

NetSuite は、2種類の異なるAPI を通じてデータへのアクセスを提供しています。使用するAPI は、Schema 接続プロパティに以下のいずれかを設定することで指定します。

SuiteTalk はNetSuite との通信に使用される、SOAP ベースの旧来のサービスです。多くのエンティティを幅広くサポートし、INSERT / UPDATE / DELETE を完全にサポートします。ただし、SuiteQL API に比べてデータを返す速度が遅くなります。このAPI ではサーバーサイドでのJOIN はサポートされていないため、これらのアクションは本製品によって完全にクライアントサイドで実行されます。
SuiteQL は新しいAPI です。JOIN、GROUP BY、集計、およびカラムフィルタリングをサーバーサイドで実行できます。そのため、データの抽出においてSuiteTalk よりも大幅に高速です。ただし、NetSuite データへのアクセスは読み取り専用です。

データを取得するだけの場合は、SuiteQL の使用をお勧めします。データの取得および変更が必要な場合は、SuiteTalk の使用をお勧めします。

SuiteTalk に接続する場合は、NetsuiteMetadataFolder を指定することをお勧めします。 NetSuite Metadata Folder は、NetSuite のメタデータファイルが格納されるフォルダです。指定しない場合は、フォルダの場所は自動的に選択されます。テーブルに関するメタデータをリスト化する際のロード時間を速くするには、このプロパティを設定してください。

NetSuite への認証

NetSuite は、以下の認証方式をサポートしています。

トークンベース認証（TBA）はOAuth 1.0 に似ています。TBA は、2020.2 以降のSuiteTalk およびSuiteQL の両方で利用可能です。
OAuth 2.0 認証（OAuth 2.0 認可コードグラントフロー）は、SuiteQL でのみ利用できます。
OAuth JWT 認証は、OAuth 2.0 クライアント認証フローであり、クライアント認証情報を含むJWT を使用してNetSuite データへのアクセスを要求します。
Basic 認証、つまり「ユーザー/パスワード」認証は、NetSuite バージョン2020.2以降、NetSuite ではサポートされなくなりました。Version 接続プロパティを2020.2 より前のバージョンに設定した場合に限り、CData Python Connector for NetSuite はUser / Password での接続を引き続きサポートしますが、すべてのお客様に対して上記のOAuth またはトークンベース認証システムへの移行を推奨します。このオプションは、Schema 接続プロパティがSuiteTalk に設定されている場合にのみ使用できます。

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

トークンベース認証（TBA）は基本的にOAuth 1.0 です。この認証メカニズムは、SuiteTalk およびSuiteQL の両方でサポートされています。

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

NetSuite UI でのトークンの作成

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

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

NetSuite で、管理者権限を持つアカウントを使用してログインします。
NetSuite ナビゲーションメニューで、設定 -> 会社にマウスを合わせ、次に機能の有効化をクリックします。機能の有効化ページが開きます。
機能の有効化ページのタブバーで、SuiteCloud をクリックします。
認証の管理セクションで、トークンベース認証を有効にします。
ページ下部の青い保存ボタンをクリックします。
NetSuite ナビゲーションメニューで、設定 -> インテグレーションにマウスを合わせ、次に統合を管理をクリックします。統合ページが開きます。
新しい統合を作成するには、新規作成をクリックします。統合ページが開きます。
認証セクションのトークンベース認証の下で、トークンベース認証チェックボックスを有効にします。
ページ上部または下部の青い保存ボタンをクリックします。読み取り専用のページが表示されます。
認証 -> クライアント資格情報セクションに、消費者キー（コンシューマーキー）および消費者シークレット（コンシューマーシークレット）が表示されます。これらの値は、OAuthClientId およびOAuthClientSecret 接続プロパティに使用するために記録してください。
- Note：コンシューマーキーとシークレットは、統合作成直後のこの画面でのみ表示されます。再度このページを開いても表示されません。
新しいトークンのロールを作成するには、NetSuite のナビゲーションメニューで設定 -> ユーザー / ロール -> ロール管理にマウスを合わせ、新規作成をクリックします。

または

既存のトークンのロールを編集するには、NetSuite ナビゲーションメニューで設定 -> ユーザー / ロール にマウスを合わせ、ロール管理をクリックします。ロール管理ページが開きます。

ロール管理ページで、「名前」列に編集したいロールがある行で、「編集」列のカスタマイズをクリックします。

どちらの操作でもロールページが開きます。
許可セクションで、設定 () ドロップダウンメニューをクリックします。
設定 () メニューで、追加ボタンの上にあるドロップダウンメニューをクリックします。
「追加」ボタンの上のドロップダウンからユーザーアクセストークンを選択し、水準をフルに設定して追加をクリックします。同様にアクセストークンの管理権限も追加します（水準も同様にフルに設定します）。
新しいトークンロールをユーザーに割り当てるには、NetSuite のナビゲーションメニューでリスト -> 従業員にマウスを合わせ、従業員をクリックします。従業員ページが開きます。
従業員ページのEDIT | VIEW列で、ロールを追加したいユーザーの行で編集をクリックします。従業員ページが開きます。
従業員ページのタブバーでアクセスタブをクリックします。追加ボタンの上にあるドロップダウンメニューから、新しい（または編集した）ロールを選択し、追加をクリックします。
新しいアクセストークンを作成するには、NetSuite のナビゲーションメニューで設定 -> ユーザー / ロールにマウスを合わせ、アクセストークンをクリックします。アクセストークンページが開きます。
アクセストークンページで、青い新しいアクセストークンボタンをクリックします。アクセストークンページが開きます。
アクセストークンページで：
- アプリケーション名を、先ほど作成した統合に設定します。
- ユーザーを作成したユーザーまたは変更したユーザーに設定します。
- ロールを、前のステップで作成または更新したのと同じロールに割り当てます。
- トークン名を任意の名前に設定します。
青い保存ボタンをクリックしてトークンを作成します。現在のページの読み取り専用バージョンが読み込まれます。
新しい読み取り専用ページのトークンID / シークレットセクションで、トークンID とトークンシークレットの値を、OAuthAccessToken およびOAuthAccessTokenSecret 接続プロパティに使用するために控えておきます。
- Note：トークン ID とシークレットは、トークン作成直後のこの画面でのみ表示されます。再度このページを開いても表示されません。

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

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

OAuth 2.0

NetSuite SuiteQL は、OAuth 2.0 認証をサポートしています。

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

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

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

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

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

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

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

AuthScheme = OAuth
AccountId = 接続するアカウント。
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 アクセストークンを自動的にリフレッシュするようにするには、次のように設定します。

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

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

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

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

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

ヘッドレスマシン

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OAuthJWT

本製品は、OAuth 2.0 クライアント認証フローをサポートし、クライアント認証情報を含むJWT を使用してNetSuite データへのアクセスを要求します。

この認証方法により、本製品はユーザーとのやりとりなし（マシン間）で使用できるようになります。

Note： OAuthJWT 認証方法は、Schema 接続プロパティがSuiteQL に設定されている場合にのみ使用できます。

証明書の生成

NetSuite のOAuth 2.0 クライアント認証フローでは、JWT がx.509 形式の証明書で署名されている必要があります。

OpenSSL を使用して有効な証明書を作成できます。以下は、ES256 暗号化を使用した証明書生成コンソールコマンドのサンプルです。

openssl req -new -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 -out public.pem -keyout private.pem

これにより、マシン上に公開キーと秘密キーのファイルが作成されます。これらのキーは、後で使用するために保存しておきます。

サポートされる証明書タイプの詳細については、NetSuite ドキュメントを参照してください。

統合レコードの作成

この認証方法に必要なクライアント認証情報のマッピングを作成する前に、統合レコードと呼ばれるアプリケーションを作成する必要があります。

統合レコードを作成するには：

NetSuite ナビゲーションメニューで、設定 -> インテグレーション -> 統合を管理にマウスを合わせ、新規をクリックします。統合ページが開きます。
名前フィールドに、統合レコードの名前を入力します。
「状態」を有効に設定します。
認証 -> トークンベース認証の下で、トークンベース認証とTBA：認証フローを無効にします。
認証 -> OAuth 2.0の下で、クライアント資格情報（マシン間）付与を有効化し、承認コード付与を無効化します。
ページを下にスクロールし、青い保存ボタンをクリックします。読み取り専用のページが表示されます。
認証 -> クライアント認証情報セクションまでスクロールダウンします。消費者キー（コンシューマーキー）の値を、後でOAuthJWTIssuer 接続プロパティで使用するために保存します。
- Note： コンシューマーキーは、統合作成直後のこの画面でのみ表示されます。再度このページを開いても表示されません。

クライアント資格証明マッピングの作成

統合レコードを作成した後、エンティティ、統合レコード、および証明書の間に関連付けを作成する必要があります。

これを行うには：

NetSuite ナビゲーションメニューで、設定 -> インテグレーションにマウスを合わせ、次にOAuth 2.0 クライアント資格証明（M2M）設定をクリックします。OAuth 2.0 クライアント資格証明（M2M）設定ページが開きます。
新規作成ボタンをクリックします。新規クライアント資格証明マッピングの作成画面が表示されます。
このウィンドウの項目を以下のように設定します。
- エンティティフィールドで、証明書に関連付けるエンティティを選択します。
- ロールフィールドで、エンティティに割り当てるロールを選択します。
- 適用フィールドで、統合レコードに付けた名前のアプリケーションを選択します。
- 証明書の下にあるファイルを選択をクリックします。先ほど生成した公開キーファイルを選択します。
青い保存ボタンをクリックします。

接続プロパティの設定

これで、この認証方法を使用するように本製品を設定するために必要なすべてのものが揃いました。

次の接続プロパティを設定します。

Schema：この認証方法は、この接続プロパティがSuiteQL に設定されている場合にのみ使用できます。
AuthScheme：OAuthJWT に設定。
JWTScope：これはJWT のスコープであり、NetSuite データに付与するアクセスレベルを指定します。これを"restlets"、"rest_webservices"、"suite_analytics"、またはそれらすべてに設定し、カンマで区切ります。
OAuthJWTHeaders："kid=XXXXX" に設定。XXXXX は以下のように取得します。NetSuite ナビゲーションメニューで、設定 -> インテグレーションにマウスを合わせ、次にOAuth 2.0 クライアント資格証明（M2M）設定をクリックします。OAuth 2.0 クライアント資格証明（M2M）設定ページが表示されます。適用列の値が先に作成された統合レコードの名前と一致する行の証明書ID 列の値を、この接続プロパティの値として使用します。
OAuthJWTCert：先ほど生成した秘密キーのマシン上のファイルパス。
OAuthJWTCertType：PEMKEY_FILE を選択。
OAuthJWTEncryption：証明書生成時に使用した暗号化方式を設定。
OAuthJWTIssuer：統合レコードの作成時に記録したコンシューマーキーの値。

同時リクエスト

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

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