Flow Production Tracking (formerly known as ShotGrid) REST API の認証について

Python知識はあるが他言語でもFlow Production TrackingのREST APIを利用したい技術者向けの認証ガイド

この記事は、Python知識はあるが他言語でもFlow Production Tracking（旧ShotGrid）のREST APIを利用したい技術者を対象としている。Flow Production Tracking向けのアプリケーションを作成する際、APIを使って情報を取得することが必要となる。その際、REST APIの認証方法についての情報が不足していることが課題である。本記事では、Flow Production Tracking (ShotGrid) REST APIの認証方法、とくにわかりにくいUser Name/Password認証について詳しくまとめる。

2. ShotGrid REST APIの認証方式

2.1 API3 と REST API の違い

Shotgun / ShotGridには主に2種類のAPIが存在する。

API3 (shotgun_api3):
- 従来から使われてきたPython用のAPI。
- Python以外からの利用はドキュメントがなく、ソースを参照する必要がある。
REST API:
- 比較的新しいHTTPベースのAPI。
- 言語に依存せず、広く利用しやすい。

2.2 REST APIの認証方式の概要

Flow Production Tracking (ShotGrid) REST APIの認証には、以下の3つの方法がある。

API Script Name/Key
User Name/Password
Session Token

それぞれ想定利用シーンが異なり、API Script Name/Keyはおもにスクリプトやサービスなど機械処理によるアクセス、 User Name/Passwordは各ユーザーが手動でアクセスする場合に使う。Session Tokenはそもそも前段でほかの手法での認証が必要となるため本記事では詳細に触れない。

2.3 ShotGrid独自の認証システム

重要: Flow Production Tracking (ShotGrid) REST APIの認証は一般的なOAuth 2.0の実装とは異なる独自の方式であり、特に以下の点に注意が必要である。

Legacy Loginの必要性: 認証にはShotGrid上で設定した「Legacy Login」パスワードを使用する必要がある
独自の認証エンドポイント: 標準のOAuth 2.0エンドポイントではなく、ShotGrid独自のエンドポイント /api/v1.1/auth/access_token を使用する
直接認証方式: ユーザー名・パスワードを直接APIに送信する方式で、OAuth 2.0の標準では非推奨とされている

ShotGrid認証はトークンベースのシステムを採用しているが、標準的なOAuth 2.0とは異なる独自の実装であることを理解しておくことが重要である。

3. User Name/Password認証の詳細

3.1 User Name/Password 認証が必要となる理由

User Name/Password認証が必要となる主なシナリオ：

ユーザー固有の権限が必要な場合：
- 各ユーザーの権限に基づいたデータアクセスが必要
- ユーザー別のアクティビティを追跡したい
クライアントアプリケーションの開発：
- デスクトップツール、プラグイン、モバイルアプリなど
- ユーザーごとに異なる設定やビューが必要
API Script認証が使えない環境：
- サイトポリシーでスクリプトキーの共有が禁止されている
- エンドユーザーが自分の認証情報でアクセスする必要がある

3.2 事前設定手順

User Name/Password認証を利用するには、事前に 各ユーザが 以下の手順を踏む必要がある。

Autodesk アカウントでの Personal Access Token (PAT) 作成
- Autodesk アカウントプロフィール設定画面にログインする
- Security > Personal Access Tokens から Generate New Token を選択
- Token 範囲 には Flow Production Tracking を選択
- Token Name に任意の名前を入力し、Generate Token を選択
- 生成された Token をコピーしておく (再表示不可のため、必ず保存する)
Flow Production Tracking (ShotGrid) での Personal Access Token の設定
- SGの管理画面 (例：URL: https:///page/account_settings)にログイン
- Account > Legacy Login and Personal Access Token に移動
- Bind Token を選択し、Token Name に任意の名前を入力し、Token に先ほどコピーした Token を入力
- Bind を選択
Flow Production Tracking (ShotGrid) での Legacy Login の設定
- Account > Legacy Login and Personal Access Token に移動
- Legacy Login を選択し、Enable Legacy Login を選択
- Change Password でパスワードを設定 (このパスワードは、User Name/Password 認証で使うパスワードとなり、Autodesk アカウントのパスワードとは異なるため注意が必要)

4. REST APIの認証とアクセス

4.1 認証フローの概要

REST API での認証フローを簡潔にまとめると：

初回アクセス時
- ✅ User Name/Password で認証
- ✅ Access Token と Refresh Token を取得
- ✅ Refresh Token を安全に保存
通常のAPI利用時
- ✅ Access Token をヘッダーに付けてリクエスト
- ✅ レスポンスを処理
Access Token失効時
- ✅ Refresh Token を使って新しい Access Token を取得
- ✅ 新しい Access Token でリクエストを再試行
Refresh Token失効時
- ✅ User Name/Password で再認証
- ✅ 新しい Access Token と Refresh Token を取得

認証フロー

4.2 Access TokenとRefresh Tokenの役割

トークンには2種類あり、それぞれ異なる役割を持つ。

Access Token: REST API にアクセスするためのトークン。有効期限が短い (約10分)
Refresh Token: Access Token を再取得するためのトークン。有効期限が長い

Access Token は有効期限が短いため、一定時間経過すると無効になる。そのため、Refresh Token を使って Access Token を再取得する必要がある。 Refresh Token を用いた Access Token の再取得では、User Name/Password を使ってログインが不要であるため、一度取得した Refresh Token を安全に保管しておく必要がある。ユーザーの視点では、User Name/Password の入力頻度を下げることができるため、利便性が向上する。そのかわり、Refresh Token の管理が必須となる。

4.3 各言語での実装例

4.3.1 User Name/Password を使った Access Token の取得

cURL

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=<username>&password=<password>" \
  https://<YourShotGridSite>/api/v1.1/auth/access_token

Python

import requests

auth_url = "https://<YourShotGridSite>/api/v1.1/auth/access_token"
payload = {
    "username": "<username>",
    "password": "<password>"  # ShotGridのLegacy Loginパスワード
}

response = requests.post(auth_url, data=payload)
token_data = response.json()
access_token = token_data["access_token"]
refresh_token = token_data["refresh_token"]

JavaScript

async function getAccessToken() {
  const authUrl = 'https://<YourShotGridSite>/api/v1.1/auth/access_token';
  const formData = new URLSearchParams({
    username: '<username>',
    password: '<password>'  // ShotGridのLegacy Loginパスワード
  });

  const response = await fetch(authUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: formData
  });

  const tokenData = await response.json();
  return {
    accessToken: tokenData.access_token,
    refreshToken: tokenData.refresh_token
  };
}

4.3.2 Access Token を使った API アクセス

cURL

# Access Token を使ってプロジェクト一覧を取得する例
curl -X GET -H "Authorization: Bearer <access_token>" \
  https://<YourShotGridSite>/api/v1.1/entity/project

Python

import requests

def get_projects(access_token):
    url = "https://<YourShotGridSite>/api/v1.1/entity/project"
    headers = {"Authorization": f"Bearer {access_token}"}
    response = requests.get(url, headers=headers)
    return response.json()

JavaScript

async function getProjects(accessToken) {
  const url = 'https://<YourShotGridSite>/api/v1.1/entity/project';
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  return await response.json();
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;

public async Task<dynamic> GetProjects(string accessToken)
{
    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Bearer", accessToken);
            
        var response = await client.GetAsync(
            "https://<YourShotGridSite>/api/v1.1/entity/project");
            
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<dynamic>(content);
    }
}

4.3.3 Refresh Token を使った Access Token の再取得

cURL

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=<refresh_token>" \
  https://<YourShotGridSite>/api/v1.1/auth/access_token

Python

def refresh_access_token(refresh_token):
    auth_url = "https://<YourShotGridSite>/api/v1.1/auth/access_token"
    payload = {
        "refresh_token": refresh_token
    }
    response = requests.post(auth_url, data=payload)
    token_data = response.json()
    return token_data["access_token"], token_data["refresh_token"]

JavaScript

async function refreshAccessToken(refreshToken) {
  const authUrl = 'https://<YourShotGridSite>/api/v1.1/auth/access_token';
  const formData = new URLSearchParams({
    refresh_token: refreshToken
  });

  const response = await fetch(authUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: formData
  });

  const tokenData = await response.json();
  return {
    accessToken: tokenData.access_token,
    refreshToken: tokenData.refresh_token
  };
}

5. 実装における考慮事項

5.1 必須実装コンポーネント

✅ ユーザー認証UI: ユーザー名/パスワード入力フォーム
✅ トークン管理:
- Access Token・Refresh Tokenの安全な保存
- 有効期限チェック
- 自動更新機能
✅ エラーハンドリング:
- 401/403エラー時のトークン再取得ロジック
- ユーザー再認証プロンプト
✅ API呼び出しラッパー: 認証ヘッダー自動付与

5.2 タイムライン: トークン更新サイクル

[初期認証]──10分──>[トークン期限切れ]─(Refresh Token利用)─>[新Access Token]
                                  ↓
                         [Refresh Token期限切れ]
                                  ↓
                     [ユーザーに再認証を要求]

5.3 主要なエラーコードと対応方法

エラーコード	意味	対応方法
401 Unauthorized	アクセストークンが無効か期限切れ	Refresh Tokenで新しいトークンを取得、それも失敗したら再認証
403 Forbidden	権限が不足している	ユーザーの権限を確認、または必要な権限を持つアカウントで再認証
429 Too Many Requests	API制限に達した	レート制限に従い、適切な間隔をあけて再リクエスト
500 Server Error	サーバー側のエラー	一定時間後に再試行、または管理者に連絡

5.4 レスポンス形式の例

Flow Production Tracking REST APIのレスポンスは基本的にJSON形式である。例えば、プロジェクト一覧を取得した場合:

{
  "data": [
    {
      "type": "Project",
      "id": 123,
      "attributes": {
        "name": "プロジェクト1",
        "sg_status": "アクティブ",
        "code": "PROJ1",
        "created_at": "2025-01-15T12:34:56Z"
      }
    },
    {
      "type": "Project",
      "id": 124,
      "attributes": {
        "name": "プロジェクト2",
        "sg_status": "アクティブ",
        "code": "PROJ2",
        "created_at": "2025-02-01T09:00:00Z"
      }
    }
  ]
}

データは通常 data キー内に配列として格納され、各オブジェクトは type, id, attributes を持つ。

6. セキュリティに関する注意点

6.1 Refresh Tokenの安全な保管

Refresh Tokenは安全に保管することが重要である。OSのキーチェーンやパスワードマネージャー、適切な暗号化を用いることを推奨する。

Python

import keyring

# Refresh Token を保存
# Windowsの場合 Credential Manager (資格マネージャ） > Windows Credential に保存される
keyring.set_password("YourFlowProductionTrackingSiteRESTAPI", "RefreshToken", refresh_token)

JavaScript (Electron)

// Electronアプリでのセキュアな保存例
const { safeStorage } = require('electron');
const fs = require('fs');

function saveToken(token) {
  const encryptedToken = safeStorage.encryptString(token);
  fs.writeFileSync('token.dat', encryptedToken);
}

function loadToken() {
  const encryptedToken = fs.readFileSync('token.dat');
  return safeStorage.decryptString(encryptedToken);
}

using System.Security.Cryptography;
using Microsoft.Win32;

public class TokenManager
{
    public static void SaveToken(string token)
    {
        // データを暗号化
        byte[] encryptedData = ProtectedData.Protect(
            System.Text.Encoding.UTF8.GetBytes(token),
            null, DataProtectionScope.CurrentUser);
            
        // レジストリに保存
        using (RegistryKey key = Registry.CurrentUser.CreateSubKey(@"SOFTWARE\YourApp"))
        {
            key.SetValue("RefreshToken", Convert.ToBase64String(encryptedData));
        }
    }
}

6.2 認証に関するその他の注意点

Autodesk Identity (Autodesk Platform Services / 旧Forge)のトークンはShotGridでは使用不可である。 Autodeskの OAuth2認証を調べているとがヒットするが、これは Flow Production Tracking (ShotGrid) の認証には使用できない。
将来的に Legacy Login 方式が変更される可能性があるため、公式ドキュメントの動向に注意する必要がある。

7. まとめ

本記事では、Flow Production Tracking (ShotGrid) REST APIにおけるUser Name/Password認証について詳しく解説した。この認証方式は一般的なOAuth 2.0とは異なる独自の実装であり、利用には事前に各ユーザーがLegacy Loginの設定を行う必要がある。

実装に際しては、Access TokenとRefresh Tokenの適切な管理が重要となる。特にRefresh Tokenは安全に保管し、有効期限やエラー処理を適切に実装することで、ユーザー体験を損なわずにAPIを利用することができる。

今後の学習には、公式の Flow Production Tracking REST API ドキュメントを参照することをお勧めする。以上。

Flow Production Tracking (formerly known as ShotGrid) REST API の認証について

目次

1. はじめに

2. ShotGrid REST APIの認証方式

2.1 API3 と REST API の違い

2.2 REST APIの認証方式の概要

2.3 ShotGrid独自の認証システム

3. User Name/Password認証の詳細

3.1 User Name/Password 認証が必要となる理由

3.2 事前設定手順

4. REST APIの認証とアクセス

4.1 認証フローの概要

4.2 Access TokenとRefresh Tokenの役割

4.3 各言語での実装例

4.3.1 User Name/Password を使った Access Token の取得

4.3.2 Access Token を使った API アクセス

4.3.3 Refresh Token を使った Access Token の再取得

5. 実装における考慮事項

5.1 必須実装コンポーネント

5.2 タイムライン: トークン更新サイクル

5.3 主要なエラーコードと対応方法

5.4 レスポンス形式の例

6. セキュリティに関する注意点

6.1 Refresh Tokenの安全な保管

6.2 認証に関するその他の注意点

7. まとめ