CUEBiC TEC BLOG

キュービックTECチームの技術ネタを投稿しております。

NetSuiteとAPI連携してみた_その1(OAuth2.0トークン認証編)

NetSuite ERP DX REST API やってみた
どうもーキュービックでテックリードをやっている尾﨑です。 本日は会計や組織データなどのマスタ管理を行なっているNetSuiteのSuiteTalk REST Web ServicesからREST API連携した時のお話をしたいと思います。
Komawoの全体アーキテクチャ
スクラッチで連携した事例は希少だと思うので、困っている方の課題解決に繋がると嬉しいです。 構成が長いので以下の3遍でご紹介したいと思います。 
・OAuth2.0トークン認証によるREST API連携★
・OAuth2.0クライアント認証によるRest API連携
・トークンベース認証によるRestlet API連携
本日はOAuth2.0トークン認証によるREST API連携方法とハマったポイントなどをご紹介したいと思います。

アーキテクチャ構成

Komawoの前身であるCBA(CUEBiC Analytics)から先行的に ドメインとして持つべきではないマスタをNetSuiteに退避し、REST APIにて同期を行いました。

困った点

  • NetSuiteの公式のドキュメントが読みづらい
    • すごく重要な設定をサラッと書いている
    • 設定方法が散らばっているので関連性が紐解きづらい
  • ノウハウ系の投稿が少ない
    • SaaSサービスによる連携サイトがほとんどで連携方法自体はブラックボックスなパターンがほとんど
    • 有償サポートでは技術的な課題は回答ができなかった
    • テクニカルサポートはフィリピンなのでビデオ会議まで時間がかかった。

解決方法

  • YouTubeの英語の解説動画を探して、何度も停止・再生をしながら設定を学ぶ
  • 設定方法とNetSuite公式ドキュメントを比較して社内ドキュメントを体系的にまとめる
  • それでも解決しない場合はテクニカルサポートに連絡して、日本語対応スタッフとテレビ電話でペアプロする

    • 事前準備

  • OAuth 2.0 Authorization Code Grant Flowによる認証方法を使用して連携を行います
  • 公式ドキュメント：NetSuite Applications Suite

    • 以下の3STEPで設定を行います。

    Q.よくある疑問 OAuth2のトークンを取得するために前提情報として[クライアントID]が必要だが、どこで設定しているのか？？

    A.NetsuiteのUI上で事前設定が必要です 設定>インテグレーション

    インテグレーション

    トークンベース認証

    インテグレーション

    APIの設定

    以下の順番で説明していきます

    前提
1.手順1Oauth2.0承認コードの取得
2.手順2.refresh tokenの取得
3.手順3.アクセストークンの取得
4.手順4.疎通テスト

    前提

    Oauth2.0の承認codeを取得するには以下の事前設定が必要 NetSuite上で設定>SuitsCloudタブ

    認証を管理>OAUTH2.0 チェックボックスを有効化にし、機能を有効化にして保存

    上記ステップを踏まない場合は、リダイレクトURLにリダイレクト前に以下のようなエラーが表示される

    手順1.Oauth2.0承認コードの取得

    NetSuiteのインテグレーションで設定した以下の情報をもとにOauth2.0の承認コードを取得する 1.API TESTERなどで、以下のエンドポイントに対して、パラメータを設定しURLを生成する

    エンドポイント

    大項目 小項目
    エンドポイント https://{account_id}.app.netsuite.com/app/login/oauth2/authorize.nl?
    HTTPメソッド -


    パラメータ 概要 /設定値
    response_type code
    client_id インテグレーションで発行したクライアントID
    redirect_uri インテグレーションで設定したリダイレクトURL
    scope rest_webservices
    state 任意の24文字以上の文字列

    2.生成したURLをブラウザにコピペして実行する。

    3.NetSuiteのログイン画面が表示されるので、２要素認証まで突破する

    4.認証画面が表示されるので、許可を押下する

    5.設定したリダイレクト先のURLにリダイレクトされる

    リダイレクトされた際のURLのパラメータからcodeを取得

    手順2.refresh tokenの取得

    codeが取得できたので、次はrefresh tokenの取得を行う

    • 事前準備：HEADERSのAuthorizationに設定するBasicコードの取得

    以下で取得した項目をheader-generaterなどで生成して取得する

    項目 概要
    クライアントID インテグレーション登録時に初回発行時のみ参照可能
    アクセスキー インテグレーション登録時に初回発行時のみ参照可能


    大項目 小項目
    エンドポイント https://{account_id}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token?
    HTTPメソッド POST


    ヘッダー 設定値
    Content-Type application/json
    Authorization Basicコード


    パラメータ 概要 /設定値
    code 手順1で取得したcode
    redirect_uri インテグレーションで設定したリダイレクトURL
    grant_type authorization_code

    APIを実行して実行結果からrefresh tokenを取得する

    手順3.アクセストークンの取得

    手順2で取得したrefresh tokenを使用してアクセストークンを取得する

    大項目 小項目
    エンドポイント https://{account_id}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token?
    HTTPメソッド POST


    ヘッダー 設定値
    Content-Type application/x-www-form-urlencoded
    Authorization Basicコード


    パラメータ 概要 /設定値
    grant_type authorization_code
    refresh_token 手順2で取得したrefresh token

    APIを実行し、アクセストークンを取得する

    手順4.疎通テスト

    手順3で取得したアクセストークンをHEADERSに設定し、APIでクエリの疎通をこなう

    大項目 小項目
    エンドポイント https://{account_id}suitetalk.api.netsuite.com/services/rest/query/v1/suiteql?
    HTTPメソッド POST


    ヘッダー 設定値
    Authorization Bearer + 手順３で取得したアクセストークン
    Content-Type application/json


    パラメータ 概要 /設定値
    limit 表示したい件数

    リクエストbodyサンプル

    {
    "q": "SELECT * FROM customrecord_cb_anken"
}

    ※1000件以上の場合は再度リクエストが必要になる

    実行が成功すると以下のようにNetsuiteのテーブル情報が取得される

    はまった点

    • アクセストークンが1週間ぐらいで切れる
    • アクセストークンが切れるとNetSuite上で規約同意を行う必要がある
    • ヘッドレスブラウザでも使わない限り自動化不可
    • カスタムフィールドに値で設定していないデータはAPIで項目として認識されない

    リフレッシュトークンが3600秒なのは分かりますが、アクセストークン2週間はかなり厳しいですね。 ECSのタスク定義の環境変数に認証情報を設定していたのであくまで素通用で運用レベルでは使えないと断定しました。 次回はこちらの弱点を克服したクライアント証明書方式による認証をご紹介したいと思います。