Shotgun APIを使ってカスタムイベントを記録する

#これはなに？
Shotgun API経由での、Shotgunへのログの記録について
自動的に残されるログではなく、意図的に任意のログを残す場合について書きます。

#EventLogEntry エンティティ
Shotgun上で、ログを記録するためのデータテーブルは**「EventLogEntry エンティティ」**です。
誰かがShotgun Webでなにかしたら（ページを開いたり、ステータスを変更したり、バージョンを閲覧したり）ログが残されます。

##特徴

- 削除不可能
- 編集不可能
- ブラウザからの操作でも、API経由でも記録される

…ログなので当然

#ログを【任意に】記録する
##前提
何もしなくてもログは記録されるんですが、
そのほかに、なんらかの目印として自前のイベントをログとして残したいときもあります。

いわゆる「カスタムイベント」です。

##使用メソッド = create
イベントを記録するためのメソッドが用意されているわけではなく、
普通に、EventLogEntry エンティティに対して**create**します

##フィールド
- event_type
 - 空欄にすることはできません。後述します
- description
 - 空欄にすると、自動的に「New Event」と書き込まれます。
- user
- entity
 - この二つは、空欄にすることもできますが書いてないと困ります。

![スクリーンショット 2016-03-25 2.04.57.png](https://qiita-image-store.s3.amazonaws.com/0/102581/201bcfb5-12e2-ff48-dfd4-694e5ec9fa11.png)
*projectとevent_typeだけの状態でうっかりcreateしてしまった例。*

ちなみにプロジェクト欄の「RTS」といえば、
こちらで連載しておられたり　＞　http://area.autodesk.jp/column/tutorial/road_to_stingray/
先日は講演もしておられました　＞　http://www.guncys.com/?p=378
完成が楽しみですね！

#event_type の書き方
event_type自体はただのテキスト欄なので自由に書き込めますが、
基本的には以下のフォーマットに合わせるのが良いでしょう

```
{何によるログか}_{どのエンティティへのログか}_{どういう操作をしたか}
```

「誰が」「どこに」「どうした」をアンダースコアでつないだものです。
標準で書き込まれるログから観察するに、アッパーキャメルケースを3要素分アンダースコアでつないだ感じです。

## 誰が

*「誰が」*は、公式wikiでは**『アプリケーション』**と書かれています。ログのほとんどはブラウザ経由の操作が締めるので「Shotgun」が入ります。
あまり細かくせず、極端な話「Shotgun『じゃない』」ことを示せればいいような気もします。
ScriptUserの名前が入るようなスクリプトにしてしまってもいいでしょう。

## どこに

*「どこに」*には**エンティティ名**そのものをいれます。

## どうした

*「どうした」*には**『アクション』**をいれます。
Shotgunの残すログを観察してみると、新規に作成したら『New』、更新したら『Change』などが入ってます。あまり長くせず1単語程度という感じです。
（『delete』メソッド＝Retirement。なぜメソッドの『create』や『update』に対応していないのかは、ちょっと謎です。データベース用語的なもの？）
ここではわざわざスクリプトを書いてログを残すわけですから、それら標準のアクションとはちがうアクションがここに代入されるのではと思います。


#例文
##書き込み
これまでの内容を踏まえて、任意のログを残すスクリプトは例えば下記のようになります

```py:
data = {}
data['project'] = PROJ
data['event_type'] = 'MyApp_Entity_SomeAction'
data['description'] = 'some action'
data['user'] = SCRIPT_USER
data['entity'] = SOME_TARGET
    
sg.create('EventLogEntry',data)
```

##取得
書き込んだログを取得する例文は下記のような感じ

```py:
eventType = 'MyApp_Entity_SomeAction'

log = sg.find_one(
                  'EventLogEntry',
                  [['event_type','is',eventType ],['project','is',PROJ]],
                  ['created_at','entity'],
                  order=[{'field_name':'id','direction':'desc'}]
                  )
```

`find_one`メソッドを使いつつ`order`で新しい順に返ってくるよう指定('desc'のとこ)することで
「最新の'Myscript_Shot_SomeAction'」をひとつ取得しています。
また、返ってくるフィールドに`'created_at'`を入れてタイムスタンプも取得します。

イベントタイプ入れれば返ってくる感じで関数化しておくといいんじゃないでしょうか。

#まとめ
- create をつかいます。
- **消せない**ので注意！

##備考
###イベントの例

普通に使ってたら（＝上記のようなことを特にしなくても）流れてくるようなイベントタイプの例を並べてみました。

- Shotgun_Task_Retirement
- Shotgun_User_Logout
- Shotgun_User_FailedLogin
- Shotgun_ProjectUserConnection_New
 - プロジェクトにスタッフをアサインした時に記録されるイベントタイプです
- Shotgun_AppWelcomeUserConnection_New
 - 新規にユーザーを招待したら記録されるやつです。多分。
- Shotgun_PageSetting_Change
- Toolkit_Desktop_ProjectLaunch
 - パイプラインツールキット経由のログ。

###参考

> How to write event driven triggers
https://support.shotgunsoftware.com/entries/44575-How-to-write-event-driven-triggers

> Event Types
https://github.com/shotgunsoftware/python-api/wiki/Event-Types


こういういいものもあります
> Shotgun Event Framework
https://github.com/shotgunsoftware/shotgunEvents