前回は、Shotgun APIを使用するための導入部分についての説明を行いました

前回の記事
Shotgun APIを初めて使う方へ - 導入編 -

今回は、Shotgun APIを実際に使用してShotgunにデータを登録し、取得や更新等を行っていきたいと思います

前回の記事で作成したフォルダやファイルを使用して進めますので、
まだ前回の記事をご覧になっていない場合は、そちらから先にご覧頂ければ幸いです

Shotgun APIでProjectを作成する

Shotgunでは、ProjectやAsset、Shotなどの各要素のことをEntityと呼びます
基本的に各Entityは、Project単位で管理が行われる仕組みとなっているため、まずはProjectの作成から入りたいと思います

Project作成用スクリプトの作成

テキストエディタに下記のコードをコピー＆ペーストし、前回の記事で作成したshotgun_api_startupフォルダの中に
create_project.pyという名前で保存します

create_project.py


# -*- coding: utf-8 -*-

import sys
from shotgun import create_shotgun_api

# 作成するProjectの名前を指定します
PROJECT_NAME = "SHOTGUN_API_STARTUP"


def create_project(shotgun_api):
  # ShotgunにProjectを作成します
  data = {"name": PROJECT_NAME,
          "sg_description": u"このProjectはShotgun APIの学習用に作成しました"}
  return shotgun_api.create(entity_type="Project",
                            data=data)


def main():
  shotgun_api = create_shotgun_api()

  print(create_project(shotgun_api))
  return 0


if __name__ == "__main__":
  sys.exit(main())

解説

Shotgunにデータを作成する際は、create 関数を使用します

引数
- entity_type
  - 指定するentity_typeによってどのEntityを作成するのかが決まります
- data
  - 指定した辞書データの内容がProjectの情報として追加されます
  - 辞書データ内のnameは必須項目となっていて、作成したいProjectの名前を指定します。名前が重複する場合はエラーが出ます
  - 辞書データ内のsg_descriptionは、Projectの説明を指定します

create関数の戻り値には、作成したProjectのidなどの情報が辞書データとして返ってきます
公式ドキュメントの方に詳しい情報が載っています


# 作成するProjectの名前を指定します
PROJECT_NAME = "SHOTGUN_API_STARTUP"


def create_project(shotgun_api):
  # ShotgunにProjectを作成します
  data = {"name": PROJECT_NAME,
          "sg_description": u"このProjectはShotgun APIの学習用に作成しました"}
  return shotgun_api.create(entity_type="Project",
                            data=data)

動作確認

動作確認をしている様子を動画にしたのでご覧頂ければと思います

ShotgunAPIでプロジェクトを作る方法 pic.twitter.com/Ph6jqyYTa4
— Tetsuya Nozawa (@lphing) January 29, 2020

手順

コマンドプロンプトを開いて、下記のコマンドを入力して実行します
※D:\shotgun_api_startupの部分は、shotgun_api_startupフォルダを作成した場所に応じて変更して下さい

cd /d D:\shotgun_api_startup
python create_project.py

Projectの作成に成功した場合は、下記のような内容がコマンドプロンプト上に出力されます

D:\shotgun_api_startup>python create_project.py
{'id': 350, 'name': 'SHOTGUN_API_STARTUP', 'sg_description': 'このProjectはShotgun API の学習用に作成しました', 'type': 'Project'}

ShotgunでProjectテーブルを見てみると、SHOTGUN_API_STARTUPという名前のProjectが作成されていることが確認出来るかと思います

作成したProjectの情報を取得する

先ほど作成したProjectの情報をAPIで取得してみます

Project取得用スクリプトの作成

テキストエディタに下記のコードをコピー＆ペーストし shotgun_api_startupフォルダの中に
get_project.pyという名前で保存します

get_project.py

# -*- coding: utf-8 -*-

import sys
from shotgun import create_shotgun_api

# 取得するProjectの名称を指定します
PROJECT_NAME = "SHOTGUN_API_STARTUP"


def get_project(shotgun_api, project_name):
  # nameがproject_nameの値に合致するものを取得対象に設定します
  filters = [["name", "is", project_name]]
  # 取得したい情報が入っているフィールドのフィールドコードを指定します
  fields = ["name", "sg_description"]
  # Shotgunからfiltersの条件に合致するProjectの情報を取得します
  return shotgun_api.find(entity_type="Project",
                          filters=filters,
                          fields=fields)


def main():
  shotgun_api = create_shotgun_api()
  print(get_project(shotgun_api, PROJECT_NAME))
  return 0


if __name__ == "__main__":
  sys.exit(main())

解説

Shotgun APIでデータを取得する際は、find 関数を使用します

引数
- entity_type
  - 指定するentity_typeによって取得するEntityを決めます
- filters
  - 取得対象を絞り込むための条件を指定します
  - 条件の指定方法に関しては、公式ドキュメントのFilter Syntaxページを参考にして下さい
- fields
  - idとtypeに関しては、デフォルトで取得対象となっています
  - idとtype以外のフィールドの値も取得する場合は、リストで対象のフィールドのフィールドコードを指定することで対象に含めることが出来ます
  - フィールドコードの確認方法については、下記の記事が参考になります
    - Field code(フィールドコード)を確認する方法

findに関する詳しい情報は公式ドキュメントに載っています

def get_project(shotgun_api, project_name):
  # nameがproject_nameの値に合致するものを取得対象に設定します
  filters = [["name", "is", project_name]]
  # 取得したい情報が入っているフィールドのフィールドコードを指定します
  fields = ["name", "sg_description"]
  # Shotgunからfiltersの条件に合致するProjectの情報を取得します
  return shotgun_api.find(entity_type="Project",
                          filters=filters,
                          fields=fields)

動作確認

コマンドプロンプトを開いて、下記のコマンドを入力して実行します
※D:\shotgun_api_startupの部分は、shotgun_api_startupフォルダを作成した場所に応じて変更して下さい

cd /d D:\shotgun_api_startup
python get_project.py

取得に成功した場合は、下記のような内容がコマンドプロンプト上に出力されます

D:\shotgun_api_startup>python get_project.py
[{'type': 'Project', 'id': 350, 'name': 'SHOTGUN_API_STARTUP', 'sg_description': 'このProjectはShotgun APIの学習用に作成しました'}]

Projectの情報を更新（変更）する

情報の取得が出来るようになったため、取得したIDを元にProjectの情報を更新したいと思います
※Shotgunに保存されている情報を更新するためには、対象のEntityのIDが必要になります

Project情報の更新用スクリプトを作成する

テキストエディタに下記のコードをコピー＆ペーストし、shotgun_api_startupフォルダの中に
update_project.pyという名前で保存します

update_project.py

# -*- coding: utf-8 -*-

import sys
import datetime
from shotgun import create_shotgun_api
from get_project import get_project

# 更新対象のProjectの名称を指定します
PROJECT_NAME = "SHOTGUN_API_STARTUP"


def update_project(shotgun_api, project_info):
  description = "このデータは、%s に更新されました" % datetime.datetime.now()
  # Shotgunから取得した情報を使ってsg_descriptionの内容を更新します
  return shotgun_api.update(entity_type=project_info.get("type"),
                            entity_id=project_info.get("id"),
                            data={"sg_description": description})


def main():
  shotgun_api = create_shotgun_api()
  # Project情報取得用スクリプトを使って情報を取得します
  project_info = get_project(shotgun_api, PROJECT_NAME)
  print(update_project(shotgun_api=shotgun_api,
                       project_info=project_info[0]))
  return 0


if __name__ == "__main__":
  sys.exit(main())

解説

Shotgun APIでデータを更新する場合は、update 関数を使用します

引数
- entity_type
  - 更新対象のEntityのtypeを指定します
- entity_id
  - 更新対象のEntityのIDを指定します
- data
  - 更新する内容を辞書型で指定します
  - 今回の場合は、sg_descriptionの値が更新されます


def update_project(shotgun_api, project_info):
  description = "このデータは、%s に更新されました" % datetime.datetime.now()
  # Shotgunから取得した情報を使ってsg_descriptionの内容を更新します
  return shotgun_api.update(entity_type=project_info.get("type"),
                            entity_id=project_info.get("id"),
                            data={"sg_description": description})

動作確認

動作確認をしている様子を動画にしたのでご覧頂ければと思います

ShotgunAPIでプロジェクトの情報を取得・更する方法 pic.twitter.com/vwEI90oJcQ
— Tetsuya Nozawa (@lphing) January 29, 2020

手順

コマンドプロンプトを開いて、下記のコマンドを入力して実行します
※D:\shotgun_api_startupの部分は、自分の環境に合わせて変更して頂ければと思います

cd /d D:\shotgun_api_startup
python update_project.py

実行に成功した場合は、下記のような内容が出力されます

D:\shotgun_api_startup>python update_project.py
{'type': 'Project', 'id': 350, 'sg_description': 'このデータは、2020-01-16 16:43:13.293248 に更新されました'}

ShotgunでProjectテーブルを見てみると、SHOTGUN_API_STARTUPのdescriptionフィールドの値が更新
されていることが確認出来るかと思います

あとがき

ここまで紹介した内容で、Shotgun APIを使用した基本的なデータ操作が出来るようになったかと思います
次回の後編では、AssetやShot、TaskなどProjectに紐づくEntityの作成方法を紹介します