Smartsheet への接続

Smartsheet は、以下の認証メソッドによる接続をサポートしています。

• 個人用アクセストークンの使用
• OAuth の使用

個人用アクセストークン

個人用トークンを使用して、自分のデータをテストし、アクセスします。個人用トークンを取得する方法は次のとおりです。

1. Smartsheet にログインします。
2. ［アカウント］をクリックして［個人用の設定］を選択します。
3. ［API アクセス］をクリックし、フォームを使用して新しいアクセストークンを生成するか、既存のアクセストークンを管理します。

AuthScheme をPersonalAccessToken に設定します。その後、PersonalAccessToken を生成したトークンに設定します。

OAuth

Smartsheet はOAuth 認証のみサポートします。Web、デスクトップ、ヘッドレスサーバーのいずれから認証する場合でも、カスタムOAuth アプリケーションの作成 で説明するとおり、 AuthScheme をOAuth に設定してカスタムOAuth アプリケーションを作成する必要があります。

以下のサブセクションでは、デスクトップアプリケーション、Web、またはヘッドレスマシンから、カスタムOAuthアプリケーションを経由して認証する方法を詳しく説明します。

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

カスタムOAuth アプリケーションの資格情報を使用して認証するには、OAuth アクセストークンを取得し、更新する必要があります。これらを設定すると、接続の準備が整います。

OAuth アクセストークンの取得およびリフレッシュ：

• OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
• OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
• CallbackURL：アプリケーションの登録時に定義されたリダイレクトURI。

接続すると、本製品 はデフォルトブラウザでSmartsheet のOAuth エンドポイントを開きます。

ログインして、アプリケーションにアクセス許可を与えます。本製品 はこれでOAuth プロセスを完了します。

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

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

Web アプリケーション

カスタムOAuth アプリケーションの資格情報を使用してWeb から認証するには、Smartsheet でカスタムOAuth アプリケーションを登録する必要があります。 それから本製品 を使用してOAuth トークンの値を取得および管理します。

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

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

• OAuthClientId：アプリケーション設定のクライアントId。
• OAuthClientSecret：アプリケーション設定のクライアントシークレット。

OAuth 交換を完了するには、以下のようにストアドプロシージャを呼び出します。

1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、CallbackURL をアプリケーション設定で指定したリダイレクトURI に設定します。 ストアドプロシージャは、OAuth エンドポイントへのURL を返します。
2. ステップ1でストアドプロシージャが返したURL に移動します。ログインしてWeb アプリケーションを認可します。コールバックURL にリダイレクトされます。
3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、リダイレクトURI のクエリ文字列のcode パラメータに設定します。

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

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

本製品 がOAuth アクセストークンを自動でリフレッシュするようにしたい場合、以下の手順に従います。

はじめてデータに接続する際、次の接続プロパティを設定します。

• InitiateOAuth：REFRESH。
• OAuthClientId：アプリケーション設定のクライアントId。
• OAuthClientSecret：アプリケーション設定のクライアントシークレット。
• OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークン。
• OAuthSettingsLocation：本製品 がOAuth 値を保存する場所のパス。これは接続間で維持されます。

その後のデータ接続では、以下の接続パラメータを設定します。

• InitiateOAuth
• OAuthSettingsLocation

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

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

1. ExpiresIn 期間（GetOAuthAccessToken が返す）が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
2. 次の接続プロパティを設定します。
   • OAuthClientId：アプリケーション設定のクライアントId。
   • OAuthClientSecret：アプリケーション設定のクライアントシークレット。

3. RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
4. 新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。これで新規接続が開かれます。

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

ヘッドレスマシン

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

• オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
• オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。

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

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

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

1. 次のプロパティを設定します。
   • InitiateOAuth：OFF。
   • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
   • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
2. 適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。
3. 返されたURL をブラウザにコピーして、ページを開きます。
4. ログインして、本製品 にアクセス許可を与えます。リダイレクトURI にリダイレクトされます。
5. リダイレクトURI に付加されるcode パラメータを控えておきます。これは、後ほどOAuthVerifier 接続プロパティを設定する際に使用します。
6. OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換するために、OAuth 認証値を指定する次の接続プロパティを設定します。
   • InitiateOAuth：REFRESH。
   • OAuthVerifier：控えておいたverifier code（リダイレクトURI のcode パラメータの値）。
   • OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId。
   • OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレット。
   • OAuthSettingsLocation：暗号化されたOAuth 認証値を指定されたファイルに永続化。
7. 接続をテストしてOAuth 設定ファイルを生成し、以下のプロパティを再設定して接続します。
   • InitiateOAuth：REFRESH。
   • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
   • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
   • OAuthSettingsLocation：暗号化されたOAuth 認証値を含むファイル。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。

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

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

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

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

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

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

Synch 接続

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

• OAuthClientId：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
• OAuthClientSecret：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。

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

ドライバーは、以下のようにOAuth プロセスを完了します。

• コールバックURL からアクセストークンを取得します。
• 古いトークンの期限が切れたときは、新しいアクセストークンを取得します。
• OAuth 値を保存し、接続間で永続化します。