これはなに？

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

EventLogEntry エンティティ

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

特徴

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

…ログなので当然

ログを【任意に】記録する

前提

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

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

使用メソッド = create

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

フィールド

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

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』に対応していないのかは、ちょっと謎です。データベース用語的なもの？）
ここではわざわざスクリプトを書いてログを残すわけですから、それら標準のアクションとはちがうアクションがここに代入されるのではと思います。

例文

書き込み

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

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)

取得

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

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

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