Skip to content
Navigation Menu
{{ message }}
-
Notifications
You must be signed in to change notification settings - Fork 4
Expand file tree
/
Copy pathindex.html
More file actions
400 lines (374 loc) · 44.5 KB
/
Copy pathindex.html
File metadata and controls
400 lines (374 loc) · 44.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: README
— Documentation by YARD 0.9.43
</title>
<link rel="stylesheet" href="css/style.css" type="text/css">
<link rel="stylesheet" href="css/common.css" type="text/css">
<script type="text/javascript">
pathId = "README";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div id="main_progress" aria-hidden="true"></div>
<div class="nav_wrap">
<iframe id="nav" src="class_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'><h1 id="ShotgridApiRuby">ShotgridApiRuby</h1>
<p><a href="https://badge.fury.io/rb/shotgrid_api_ruby"><img src="https://badge.fury.io/rb/shotgrid_api_ruby.svg" alt="Gem Version" /></a>
<img src="https://github.com/shotgunsoftware/shotgrid_api_ruby/workflows/Test%20and%20Release/badge.svg" alt="Test and Release badge" /></p>
<p>A gem to integrate with shotgrid REST API easily.</p>
<h2 id="Installation">Installation</h2>
<p>Add this line to your application's Gemfile:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>shotgrid_api_ruby</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>And then execute:</p>
<pre class="code ruby"><code class="ruby">$ bundle
</code></pre>
<p>Or install it yourself as:</p>
<pre class="code ruby"><code class="ruby">$ gem install shotgrid_api_ruby
</code></pre>
<h2 id="Usage">Usage</h2>
<h3 id="Client_instantiation">Client instantiation</h3>
<p>For creating a new client you need to provide two values.</p>
<ul>
<li>One to identify the shotgrid site:
<ul>
<li>Can be <code>shotgun_site</code>: which is the <code>xxx</code> part in <code>https://xxx.shotgunstudio.com</code></li>
<li>Can be <code>shotgrid_site</code>: which is the <code>xxx</code> part in <code>https://xxx.shotgrid.autodesk.com</code></li>
<li>Can be <code>site_url</code>: which is the full url to your site</li>
</ul>
</li>
<li>One to <code>auth</code> you see <em>Authentication</em> lower in this guide.</li>
</ul>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="ShotgridApiRuby.html" title="ShotgridApiRuby (module)">ShotgridApiRuby</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="ShotgridApiRuby.html#new-class_method" title="ShotgridApiRuby.new (method)">new</a></span></span><span class='lparen'>(</span><span class='label'>shotgrid_site:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>i-love-shotgrid</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>auth:</span> <span class='lbrace'>{</span><span class='label'>client_id:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>my_nice_script</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>client_secret:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>CantTouchThis</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Authentication">Authentication</h3>
<p>Any kind of authentication specified <a href="https://developer.shotgunsoftware.com/rest-api/#authentication">here</a> is implemented</p>
<h4 id="Client_Credentials">Client Credentials</h4>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="ShotgridApiRuby.html" title="ShotgridApiRuby (module)">ShotgridApiRuby</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="ShotgridApiRuby.html#new-class_method" title="ShotgridApiRuby.new (method)">new</a></span></span><span class='lparen'>(</span><span class='label'>shotgrid_site:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>xxx</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>auth:</span> <span class='lbrace'>{</span><span class='label'>client_id:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>script_name</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>client_secret:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>script_secret</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h4 id="Password_Credentials">Password Credentials</h4>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="ShotgridApiRuby.html" title="ShotgridApiRuby (module)">ShotgridApiRuby</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="ShotgridApiRuby.html#new-class_method" title="ShotgridApiRuby.new (method)">new</a></span></span><span class='lparen'>(</span><span class='label'>shotgrid_site:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>xxx</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>auth:</span> <span class='lbrace'>{</span><span class='label'>username:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>login</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>password</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h4 id="Session_Token">Session Token</h4>
<p><strong>We highly advise not using this for a long term script as this won't be a stable value over time</strong></p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="ShotgridApiRuby.html" title="ShotgridApiRuby (module)">ShotgridApiRuby</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="ShotgridApiRuby.html#new-class_method" title="ShotgridApiRuby.new (method)">new</a></span></span><span class='lparen'>(</span><span class='label'>shotgrid_site:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>xxx</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>auth:</span> <span class='lbrace'>{</span><span class='label'>session_token:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>session_token</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h4 id="Refresh_Token">Refresh Token</h4>
<p><strong>We highly advise not using this for a long term script as this won't be a stable value over time</strong></p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="ShotgridApiRuby.html" title="ShotgridApiRuby (module)">ShotgridApiRuby</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="ShotgridApiRuby.html#new-class_method" title="ShotgridApiRuby.new (method)">new</a></span></span><span class='lparen'>(</span><span class='label'>shotgrid_site:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>xxx</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>auth:</span> <span class='lbrace'>{</span><span class='label'>refresh_token:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>refresh_token</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h3 id="ShotgridCallError">ShotgridCallError</h3>
<p>Every ShotGrid call resulting in an error will throw a ShotgridCallError. This error class derive from StandardError and will implement 2 extra methods:</p>
<ul>
<li><code>#response</code> => Will returns the original HTTP response (a Faraday::Response).</li>
<li><code>#status</code> => This method is a shortcut to get the status from the response.</li>
</ul>
<p>exemple</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>begin</span>
<span class='comment'># A ShotGrid call resulting in a error
</span><span class='kw'>rescue</span> <span class='const'>StandardError</span> <span class='op'>=></span> <span class='id identifier rubyid_e'>e</span>
<span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_backtrace'>backtrace</span> <span class='comment'># Will behave as a normal StandardError
</span> <span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_response'>response</span><span class='period'>.</span><span class='id identifier rubyid_body'>body</span> <span class='comment'># Original unparsed body from ShotGrid response
</span> <span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_status'>status</span> <span class='comment'># Status code from ShotGrid answer
</span><span class='kw'>end</span>
</code></pre>
<h3 id="Server_Infos">Server Infos</h3>
<p>Get general server infos:</p>
<pre class="code ruby"><code class="ruby">client.server_info.get
# #<OpenStruct
shotgun_version="v8.6.0.0-dev (build 12864de)",
api_version="v1",
shotgun_version_number="8.6.0.0-dev",
shotgun_build_number="12864de",
portfolio_version="UNKNOWN",
unified_login_flow_enabled=true,
user_authentication_method="default">
</code></pre>
<h3 id="Preferences">Preferences</h3>
<p>Get some preferences infos:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_prefs'>prefs</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_preferences'>preferences</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span>
<span class='id identifier rubyid_prefs'>prefs</span><span class='period'>.</span><span class='id identifier rubyid_to_h'>to_h</span><span class='period'>.</span><span class='id identifier rubyid_keys'>keys</span>
<span class='comment'># [:format_date_fields,
</span><span class='comment'># :date_component_order,
</span><span class='comment'># :format_time_hour_fields,
</span><span class='comment'># :format_currency_fields_display_dollar_sign,
</span><span class='comment'># :format_currency_fields_decimal_options,
</span><span class='comment'># :format_currency_fields_negative_options,
</span><span class='comment'># :format_number_fields,
</span><span class='comment'># :format_float_fields,
</span><span class='comment'># :format_float_fields_rounding,
</span><span class='comment'># :format_footage_fields,
</span><span class='comment'># :support_local_storage,
</span><span class='comment'># :view_master_settings,
</span><span class='comment'># :duration_units,
</span><span class='comment'># :hours_per_day,
</span><span class='comment'># :last_day_work_week]
</span></code></pre>
<h3 id="Entities">Entities</h3>
<p>Querying entities is done by accessing the named method</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span> <span class='comment'># => ShotgridApiRuby::Entities …
</span></code></pre>
<p>As entities can be user defined the client will try to answer to any unknown type with an entity call so any of those calls will returns the same thing:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_asset'>asset</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_entities'>entities</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Asset</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_entities'>entities</span><span class='lparen'>(</span><span class='symbol'>:Assets</span><span class='rparen'>)</span>
</code></pre>
<p>Any not yet implemented call can be accessed through the connection: <code>client.assets.connection</code></p>
<h4 id="Entity">Entity</h4>
<p>Returned entity will try to behave as nicely as possible.</p>
<p>An entity will always answer to:</p>
<ul>
<li>.type : the type of the entity</li>
<li>.id : the id of the entity</li>
<li>.relationships : a hash of relationships</li>
<li>.links : a hash of links to other entities</li>
<li>.attributes : An object answering to any available attributes</li>
</ul>
<p>It will also answer to any method that is present in the attributes:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_assets'>assets</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>code</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_type'>type</span> <span class='comment'># => "Asset"
</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span> <span class='comment'># => 726
</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_attributes'>attributes</span><span class='period'>.</span><span class='id identifier rubyid_code'>code</span> <span class='comment'># => "Buck"
</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_code'>code</span> <span class='comment'># => "Buck"
</span></code></pre>
<h3 id="Search">Search</h3>
<h4 id="all">all</h4>
<p>The all call will return all possible entities.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
</code></pre>
<h4 id="search">search</h4>
<p>Does the same thing as <code>all</code></p>
<h4 id="first">first</h4>
<p>Will return only the first entity found (same thing as setting the page_size to 1 and then getting the first result)</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
</code></pre>
<h4 id="arguments">arguments</h4>
<h5 id="fields">fields</h5>
<p>This attribute describe the wanted fields in the returned entity</p>
<p>Can be a string describing wanted fields: <code>'code'</code> or <code>'code,description'</code>
Or an array for better readability: <code>[:code, 'description']</code></p>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='comma'>,</span> <span class='symbol'>:description</span><span class='rbracket'>]</span><span class='rparen'>)</span>
</code></pre>
<h5 id="sort">sort</h5>
<p>Describe how you want your entities to be sorted.</p>
<p>Can be either:</p>
<ul>
<li>A string: <code>'code'</code> or <code>'code,-description'</code> (the <code>-</code> asking for a descending order)</li>
<li>An array for better readability: <code>[:code, '-description']</code></li>
<li>A hash for ease of use: <code>{code: 'asc', description: :desc}</code></li>
</ul>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='comma'>,</span> <span class='symbol'>:description</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>sort:</span> <span class='lbrace'>{</span><span class='label'>code:</span> <span class='symbol'>:asc</span><span class='comma'>,</span> <span class='label'>description:</span> <span class='symbol'>:desc</span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h5 id="logical_operator">logical_operator</h5>
<p>Default: "and"</p>
<p>This will be only used on complex queries. This is how we treat multiple first level conditions.</p>
<p>Accepted values: 'and', 'or'</p>
<h5 id="filter">filter</h5>
<p>For simple filters, the filter field is waiting for a hash.</p>
<p>Each value is:</p>
<ul>
<li>A string: then a <code>is</code> filter will be used</li>
<li>An array: then a <code>in</code> filter will be used</li>
</ul>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='comma'>,</span> <span class='symbol'>:description</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>filter:</span> <span class='lbrace'>{</span><span class='label'>code:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Buck</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:Darcy</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>description:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>I LOVE SG</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<p>For complex filters, see the documentation <a href="https://developer.shotgunsoftware.com/rest-api/#searching">here</a>.</p>
<p>If the filters are complex there's many cases:</p>
<ul>
<li>If they are a hash containing logical_operator and conditions => we will use them</li>
<li>If the filter is <strong>not</strong> a hash => we will use it without translation</li>
<li>If the filter is a hash not containing "conditions". We will try to translate this to SG compatible query.</li>
</ul>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span>
<span class='label'>filter:</span> <span class='lbrace'>{</span>
<span class='label'>project:</span> <span class='lbrace'>{</span> <span class='label'>id:</span> <span class='int'>2</span> <span class='rbrace'>}</span><span class='comma'>,</span>
<span class='label'>sg_status_list:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>act</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>hld</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>omt</span><span class='tstring_end'>"</span></span><span class='rbracket'>]</span>
<span class='rbrace'>}</span><span class='comma'>,</span>
<span class='rparen'>)</span>
<span class='comment'># Will be translated to:
</span><span class='lbrace'>{</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>filters</span><span class='tstring_end'>"</span></span><span class='op'>=></span><span class='lbrace'>{</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>conditions</span><span class='tstring_end'>"</span></span><span class='op'>=></span> <span class='lbracket'>[</span>
<span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>project.Project.id</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>is</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='int'>2</span><span class='rbracket'>]</span><span class='comma'>,</span>
<span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>sg_status_list</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>in</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>act</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>hld</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>omt</span><span class='tstring_end'>"</span></span><span class='rbracket'>]</span><span class='rbracket'>]</span>
<span class='rbracket'>]</span><span class='comma'>,</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>logical_operator</span><span class='tstring_end'>"</span></span><span class='op'>=></span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>and</span><span class='tstring_end'>"</span></span>
<span class='rbrace'>}</span>
<span class='rbrace'>}</span>
</code></pre>
<p>The complexity of calling a different route and passing different headers/body/params will be taken care of automatically.</p>
<h5 id="page">page</h5>
<p>You can ask for any page size or page number.</p>
<ul>
<li><code>page</code>: set the page number.</li>
<li><code>page_size</code>: set the size of each page.</li>
</ul>
<p>Any of the two can be omited. Their type should be a number but it'll work with a string</p>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>page:</span> <span class='int'>3</span><span class='comma'>,</span> <span class='label'>page_size:</span> <span class='int'>10</span><span class='rparen'>)</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>page:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>3</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>page_size:</span> <span class='int'>10</span><span class='rparen'>)</span>
</code></pre>
<h5 id="options">options</h5>
<p>Special options can be added:</p>
<ul>
<li>retired: a flag telling if the returned entities should be retired or not</li>
<li>include_archived_projects: a flag telling if the archived projets should be included int the search</li>
</ul>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>retired:</span> <span class='kw'>true</span><span class='rparen'>)</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span><span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>include_archived_projects:</span> <span class='kw'>true</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Finding_one_element">Finding one element</h3>
<p><code>find</code> function on <code>entities</code> allow you to get one element in particular.</p>
<p>It accepts (all arguments are optional):</p>
<ul>
<li>fields: string, symbol or array of fields</li>
<li>retired: boolean specifying if the record is retired</li>
<li>include_archived_projects: boolean specifying if the entity is part of an archived project</li>
</ul>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='int'>724</span><span class='comma'>,</span> <span class='label'>fields:</span> <span class='lbracket'>[</span><span class='symbol'>:code</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>description</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>retired:</span> <span class='kw'>false</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Create">Create</h3>
<p>Will create the entity referenced by the id with the following fields.
If successful, it will return the newly created entity.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_create'>create</span><span class='lparen'>(</span><span class='label'>code:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>New Asset</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>project:</span> <span class='lbrace'>{</span><span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Project</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>id:</span> <span class='int'>63</span><span class='rbrace'>}</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Update">Update</h3>
<p>Will update the entity referenced by the id with the following fields.
If successful, it will return the modified entity.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_update'>update</span><span class='lparen'>(</span><span class='int'>1226</span><span class='comma'>,</span> <span class='label'>code:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Updated Asset</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>sg_status_list:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>fin</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
</code></pre>
<h3 id="Delete">Delete</h3>
<p>Will destroys the entity referenced by the id. Will return true if successful.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='lparen'>(</span><span class='int'>1226</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Revive">Revive</h3>
<p>Will try to revive the entity referenced by the id. Will return true if successful.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_revive'>revive</span><span class='lparen'>(</span><span class='int'>1226</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Summarize">Summarize</h3>
<p>Will summarize data for an entity type.</p>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># Simplest example
</span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_summarize'>summarize</span><span class='lparen'>(</span><span class='label'>summary_fields:</span> <span class='lbrace'>{</span><span class='label'>id:</span> <span class='symbol'>:count</span><span class='rbrace'>}</span><span class='rparen'>)</span>
<span class='comment'># Full complex example
</span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_summarize'>summarize</span><span class='lparen'>(</span>
<span class='label'>filter:</span> <span class='lbrace'>{</span> <span class='label'>project:</span> <span class='lbrace'>{</span> <span class='label'>id:</span> <span class='int'>122</span> <span class='rbrace'>}</span><span class='comma'>,</span> <span class='label'>sg_status_list:</span> <span class='symbol'>:act</span> <span class='rbrace'>}</span><span class='comma'>,</span>
<span class='label'>logical_operator:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>or</span><span class='tstring_end'>'</span></span><span class='comma'>,</span>
<span class='label'>include_archived_projects:</span> <span class='kw'>true</span><span class='comma'>,</span>
<span class='label'>grouping:</span> <span class='lbrace'>{</span>
<span class='label'>code:</span> <span class='lbrace'>{</span><span class='label'>direction:</span> <span class='symbol'>:desc</span><span class='comma'>,</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>exact</span><span class='tstring_end'>'</span></span><span class='rbrace'>}</span>
<span class='rbrace'>}</span><span class='comma'>,</span>
<span class='label'>summary_fields:</span> <span class='lbrace'>{</span> <span class='label'>id:</span> <span class='symbol'>:count</span> <span class='rbrace'>}</span>
<span class='rparen'>)</span>
<span class='comment'># Raw shotgrid queries
</span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_summarize'>summarize</span><span class='lparen'>(</span>
<span class='label'>grouping:</span> <span class='lbracket'>[</span>
<span class='lbrace'>{</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>field</span><span class='label_end'>":</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>sg_asset_type</span><span class='tstring_end'>"</span></span><span class='comma'>,</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>type</span><span class='label_end'>":</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>exact</span><span class='tstring_end'>"</span></span><span class='comma'>,</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>direction</span><span class='label_end'>":</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>asc</span><span class='tstring_end'>"</span></span>
<span class='rbrace'>}</span>
<span class='rbracket'>]</span><span class='comma'>,</span>
<span class='label'>summary_fields:</span> <span class='lbracket'>[</span>
<span class='lbrace'>{</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>field</span><span class='label_end'>":</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>id</span><span class='tstring_end'>"</span></span><span class='comma'>,</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>type</span><span class='label_end'>":</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>count</span><span class='tstring_end'>"</span></span>
<span class='rbrace'>}</span>
<span class='rbracket'>]</span><span class='comma'>,</span>
<span class='rparen'>)</span>
</code></pre>
<p>It accepts the same <code>filter</code> and <code>logical_operator</code> as a <code>search</code> will.</p>
<h4 id="Summary_fields">Summary fields</h4>
<p>Those can have two forms:</p>
<h5 id="The_normal_API_form">The normal API form</h5>
<p>You need to supply the summary_fields as an array and it will be passed directly to the SG REST API</p>
<h4 id="The_convenient_form">The convenient form</h4>
<p>Using an array isn't very convenient most of the time. You can use a hash instead and it will be translated into a "SG summary_fields array".</p>
<p>Each key of the hash is the field name and the corresponding value is the type a summary you want (can be a string or a symbol)</p>
<h4 id="Grouping">Grouping</h4>
<p>Those can have two forms:</p>
<h5 id="The_normal_API_form">The normal API form</h5>
<p>You need to supply the grouping as an array and it will be passed directly to the SG REST API</p>
<h4 id="The_convenient_form">The convenient form</h4>
<p>Using an array isn't very convenient most of the time. You can use a hash instead and it will be translated into a "SG grouping array".</p>
<p>Each key of the hash is the field name and the corresponding value can either be :</p>
<ul>
<li>A String/Symbol and then will be used a a direction. The type will be 'exact'</li>
<li>A Hash with optional 'type' and 'direction' keys. If a key is not specified it will be 'exact' and 'asc' respectively.</li>
</ul>
<h3 id="Count">Count</h3>
<p>This is a helper for more a readable count summary. This can be passed <code>filter</code> and <code>logical_operator</code>.</p>
<p>Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_count'>count</span>
<span class='comment'># This will be equivalent as doing:
</span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_summarize'>summarize</span><span class='lparen'>(</span><span class='label'>summary_fields:</span> <span class='lbracket'>[</span><span class='lbrace'>{</span><span class='label'>type:</span> <span class='symbol'>:record_count</span><span class='comma'>,</span> <span class='label'>field:</span> <span class='symbol'>:id</span><span class='rbrace'>}</span><span class='rbracket'>]</span><span class='rparen'>)</span>
</code></pre>
<h3 id="Schema">Schema</h3>
<p>Those calls allow to inspect the schema for a shotgrid site.</p>
<h4 id="Entity">Entity</h4>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_schema'>schema</span>
</code></pre>
<h4 id="Entity_fields">Entity fields</h4>
<p>Fetch the different fields available on an entity type and their definition.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_fields'>fields</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_assets'>assets</span><span class='period'>.</span><span class='id identifier rubyid_fields'>fields</span>
<span class='id identifier rubyid_fields'>fields</span><span class='period'>.</span><span class='id identifier rubyid_code'>code</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span> <span class='comment'># => "Asset Name"
</span><span class='id identifier rubyid_fields'>fields</span><span class='period'>.</span><span class='id identifier rubyid_code'>code</span><span class='period'>.</span><span class='id identifier rubyid_properties'>properties</span><span class='period'>.</span><span class='id identifier rubyid_summary_default'>summary_default</span> <span class='comment'># => "none"
</span></code></pre>
<h3 id="Non_implemented_calls">Non implemented calls</h3>
<p>All calls which are not yet implemented can be done through the <code>connection</code> method. This method will still take care of the authentication for you.</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="ShotgridApiRuby.html" title="ShotgridApiRuby (module)">ShotgridApiRuby</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="ShotgridApiRuby.html#new-class_method" title="ShotgridApiRuby.new (method)">new</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_…'>…</span><span class='rparen'>)</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_connection'>connection</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/entity/assets</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'># => #<Faraday::Response:xxx @on_complete_callbacks=[], @env=#<Faraday::Env @method=:get @body="{\"data\":[{\"type\":\"Asset\",\"attributes\":{},\"relationships\":{},\"id\":726 …
</span></code></pre>
<h2 id="Development">Development</h2>
<p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>rake spec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
<p>To install this gem onto your local machine, run <code>bundle exec rake install</code>. To release a new version, update the version number in <code>version.rb</code>, and then run <code>bundle exec rake release</code>, which will create a git tag for the version, push git commits and tags, and push the <code>.gem</code> file to <a href="https://rubygems.org">rubygems.org</a>.</p>
<p>Every commit/push is checked by overcommit.</p>
<h2 id="Contributing">Contributing</h2>
<p>Bug reports and pull requests are welcome on GitHub at <a href="https://github.com/shotgunsoftware/shotgrid_api_ruby">https://github.com/shotgunsoftware/shotgrid_api_ruby</a>.</p>
<h2 id="License">License</h2>
<p>The gem is available as open source under the terms of the <a href="https://opensource.org/licenses/MIT">MIT License</a>.</p></div></div>
<div id="footer">
Generated on Sun May 10 11:22:59 2026 by
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.43 (ruby-3.3.11).
</div>
</div>
</body>
</html>
You can’t perform that action at this time.