Shotgun APIを初めて使う方へ - データ操作編・前編 -

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

前回の記事
[Shotgun APIを初めて使う方へ - 導入編 -](https://qiita.com/Tetsuya_Nozawa/private/da08c057febf19a2a83b)

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

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

# Shotgun APIでProjectを作成する

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

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

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

```python: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にデータを作成する際は、<b>create</b> 関数を使用します

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

create関数の戻り値には、作成したProjectのidなどの情報が辞書データとして返ってきます
[公式ドキュメント](http://developer.shotgunsoftware.com/python-api/reference.html?highlight=shotgun#shotgun_api3.shotgun.Shotgun.create)の方に詳しい情報が載っています

```python

# 作成する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)

```

## 動作確認

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

<blockquote class="twitter-tweet" data-conversation="none"><p lang="ja" dir="ltr">ShotgunAPIでプロジェクトを作る方法 <a href="https://t.co/Ph6jqyYTa4">pic.twitter.com/Ph6jqyYTa4</a></p>&mdash; Tetsuya Nozawa (@lphing) <a href="https://twitter.com/lphing/status/1222470241118113792?ref_src=twsrc%5Etfw">January 29, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> 

### 手順
コマンドプロンプトを開いて、下記のコマンドを入力して実行します
※<b>D:\shotgun_api_startup</b>の部分は、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テーブルを見てみると、<b>SHOTGUN_API_STARTUP</b>という名前のProjectが作成されていることが確認出来るかと思います
<img width="965" alt="2020-01-20_16h30_58.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110677/beaeedfd-4aea-bc52-2d58-62d103ad61c7.png">

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

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

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

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

```python: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でデータを取得する際は、<b>find</b> 関数を使用します

* 引数
    * <b>entity_type</b> 
        * 指定するentity_typeによって取得するEntityを決めます
    * <b>filters</b>  
        * 取得対象を絞り込むための条件を指定します
        * 条件の指定方法に関しては、[公式ドキュメントのFilter Syntaxページ](https://developer.shotgunsoftware.com/python-api/filter_syntax.html)を参考にして下さい
    * <b>fields</b>  
        * idとtypeに関しては、デフォルトで取得対象となっています
        * idとtype以外のフィールドの値も取得する場合は、リストで対象のフィールドの<b>フィールドコード</b>を指定することで対象に含めることが出来ます 
        * フィールドコードの確認方法については、下記の記事が参考になります  
            * [Field code(フィールドコード)を確認する方法](https://support.borndigital.co.jp/hc/ja/articles/360005387493-Field-code-%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%82%B3%E3%83%BC%E3%83%89-%E3%82%92%E7%A2%BA%E8%AA%8D%E3%81%99%E3%82%8B%E6%96%B9%E6%B3%95)

findに関する詳しい情報は [公式ドキュメント](http://developer.shotgunsoftware.com/python-api/reference.html?highlight=shotgun#shotgun_api3.shotgun.Shotgun.find)に載っています

```python
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)
```

## 動作確認

コマンドプロンプトを開いて、下記のコマンドを入力して実行します
※<b>D:\shotgun_api_startup</b>の部分は、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情報の更新用スクリプトを作成する
テキストエディタに下記のコードをコピー＆ペーストし、<b>shotgun_api_startup</b>フォルダの中に
<b>update_project.py</b>という名前で保存します

```python: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でデータを更新する場合は、<b>update</b> 関数を使用します

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

```python

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})
```

## 動作確認


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

<blockquote class="twitter-tweet" data-conversation="none"><p lang="ja" dir="ltr">ShotgunAPIでプロジェクトの情報を取得・更する方法 <a href="https://t.co/vwEI90oJcQ">pic.twitter.com/vwEI90oJcQ</a></p>&mdash; Tetsuya Nozawa (@lphing) <a href="https://twitter.com/lphing/status/1222470420042936320?ref_src=twsrc%5Etfw">January 29, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> 

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

```
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フィールドの値が更新
されていることが確認出来るかと思います
<img width="965" alt="2020-01-20_16h29_40.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110677/526f0a71-43ad-7436-9a56-873b63a77b6f.png">

# あとがき

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