|
2 | 2 | Authentication |
3 | 3 | ############## |
4 | 4 |
|
5 | | -In order to communicate with your Shotgun server via the API, you must provide valid authentication credentials. The API allows you to authenticate with user-based, or script-based credentials. |
| 5 | +In order to communicate with your ShotGrid server via the API, you must provide valid authentication credentials. The API allows you to authenticate with user-based, or script-based credentials. |
6 | 6 |
|
7 | 7 | ************************* |
8 | 8 | User-based Authentication |
9 | 9 | ************************* |
10 | | -When authenticating as a user, you provide your normal login and password when instantiating your :class:`shotgun_api3.Shotgun` object. The actions performed by this instance will be limited to your permission level just as they are in the Shotgun web application. :: |
| 10 | +When authenticating as a user, you provide your normal login and password when instantiating your :class:`shotgun_api3.Shotgun` object. The actions performed by this instance will be limited to your permission level just as they are in the web application. :: |
11 | 11 |
|
12 | | - sg = shotgun_api3.Shotgun("https://piedpiper.shotgunstudio.com", |
| 12 | + sg = shotgun_api3.Shotgun("https://my-site.shotgrid.autodesk.com", |
13 | 13 | login="rhendriks", |
14 | 14 | password="c0mPre$Hi0n") |
15 | 15 |
|
16 | 16 |
|
17 | 17 | *************************** |
18 | 18 | Script-based Authentication |
19 | 19 | *************************** |
20 | | -In order to authenticate as a script, your script must be :ref:`registered with Shotgun and have a valid API key <setting_up_shotgun>`. When creating your :class:`shotgun_api3.Shotgun` object, provide the ``script_name`` and ``api_key``.:: |
| 20 | +In order to authenticate as a script, your script must be :ref:`registered with ShotGrid and have a valid API key <setting_up_shotgrid>`. When creating your :class:`shotgun_api3.Shotgun` object, provide the ``script_name`` and ``api_key``.:: |
21 | 21 |
|
22 | | - sg = shotgun_api3.Shotgun("https://piedpiper.shotgunstudio.com", |
| 22 | + sg = shotgun_api3.Shotgun("https://my-site.shotgrid.autodesk.com", |
23 | 23 | script_name="compress", |
24 | 24 | api_key="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef") |
25 | 25 |
|
26 | | -.. note:: When using script-based authentication, we **strongly** recommend you register each script separately with Shotgun and have individual API keys for each. This allows you to track down each of your scripts and the actions they are performing much more accurately in the event logs. |
| 26 | +.. note:: When using script-based authentication, we **strongly** recommend you register each script separately with ShotGrid and have individual API keys for each. This allows you to track down each of your scripts and the actions they are performing much more accurately in the event logs. |
27 | 27 |
|
28 | 28 |
|
29 | | -.. _setting_up_shotgun: |
| 29 | +.. _setting_up_shotgrid: |
30 | 30 |
|
31 | 31 | Adding Script Users |
32 | 32 | =================== |
33 | | -If you'll be using script-based authentication, you need to create a Script entity in Shotgun. To create a new key, click the + button on the "Scripts" page in the Admin section and give your script a useful name. It's a good idea to add any other relevant information that be be helpful to your other friendly Shotgun users such as a description of what the script does that is using this key, the email address of the maintainer, etc.: |
| 33 | +If you'll be using script-based authentication, you need to create a Script entity in ShotGrid. To create a new key, click the + button on the "Scripts" page in the Admin section and give your script a useful name. It's a good idea to add any other relevant information that be be helpful to your other friendly ShotGrid users such as a description of what the script does that is using this key, the email address of the maintainer, etc.: |
34 | 34 |
|
35 | 35 | .. image:: images/scripts_page.png |
36 | 36 |
|
37 | | -Once you save your new Script entity, Shotgun will automatically generate an application key which will act as the script's password. The key will look something like this: ``0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef``. |
| 37 | +Once you save your new Script entity, ShotGrid will automatically generate an application key which will act as the script's password. The key will look something like this: ``0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef``. |
38 | 38 |
|
39 | 39 | Why have different application keys for different scripts? |
40 | 40 | ========================================================== |
41 | 41 | We recommend you create a new Script entity (and application key) for each script that is using script-based authentication so you can accurately log what scripts are doing what in case one of them causes problems. This will also allow you to better see what scripts are performing what actions in the EventLog. We've found that even though you may *think* you'll probably never need to know, the extra 2 minutes of setup now can prevent hours of headache in the future. |
42 | 42 |
|
43 | 43 | Event Logging |
44 | 44 | ============= |
45 | | -By default, events generated by scripts using an script-based authentication are logged in Shotgun's event log. You can turn this off by un-checking the "Generate Events" checkbox either in the script detail page or from the main Scripts admin page in Shotgun. |
| 45 | +By default, events generated by scripts using an script-based authentication are logged in ShotGrid's event log. You can turn this off by un-checking the "Generate Events" checkbox either in the script detail page or from the main Scripts admin page in ShotGrid. |
46 | 46 |
|
47 | 47 | .. note:: Turning off event logging will also prevent any email notifications from being triggered by your scripts since the email notifier relies on the event log to find events to notify for. |
48 | 48 |
|
49 | | -Scripts using user-based authentication will generate events similarly to if you were performing the same actions in the Shotgun web application, though there is some additional metadata stored in the ``EventLogEntry`` that identifies the event as created from a script acting on behalf of the user. |
| 49 | +Scripts using user-based authentication will generate events similarly to if you were performing the same actions in the ShotGrid web application, though there is some additional metadata stored in the ``EventLogEntry`` that identifies the event as created from a script acting on behalf of the user. |
50 | 50 |
|
51 | 51 | Why would you want to turn event logging off for scripts? |
52 | 52 | --------------------------------------------------------- |
53 | | -It is an optimization that is not used often, but some users have integration scripts that are pushing data into Shotgun just for reference, like publishes from their asset management system. This publish data is never changed later, so the data itself has the entire history, and the events would just clutter the event log. The event log can grow very large. So if you have no need to audit the history of what your script does, and it's generating an large amount of event log entries, you may find it's not necessary to create these events. |
| 53 | +It is an optimization that is not used often, but some users have integration scripts that are pushing data into ShotGrid just for reference, like publishes from their asset management system. This publish data is never changed later, so the data itself has the entire history, and the events would just clutter the event log. The event log can grow very large. So if you have no need to audit the history of what your script does, and it's generating an large amount of event log entries, you may find it's not necessary to create these events. |
54 | 54 |
|
55 | 55 | *********** |
56 | 56 | Permissions |
57 | 57 | *********** |
58 | | -Users and scripts are both bound by the restrictions of their permission role in Shotgun. The permission role is assigned by the **Permission Role** field for each entity type. |
| 58 | +Users and scripts are both bound by the restrictions of their permission role in ShotGrid. The permission role is assigned by the **Permission Role** field for each entity type. |
59 | 59 |
|
60 | | -For Scripts, the default permission role is "API Admin User" which allows full access to create, update, and delete entities and fields, including editing the "date created" audit field and creating event log entries. If you have other permission roles for ApiUsers, you can set the default role that will be assigned when a new script is created, in your Shotgun site preferences. |
| 60 | +For Scripts, the default permission role is "API Admin User" which allows full access to create, update, and delete entities and fields, including editing the "date created" audit field and creating event log entries. If you have other permission roles for ApiUsers, you can set the default role that will be assigned when a new script is created, in your ShotGrid site preferences. |
61 | 61 |
|
62 | | -When using user-based authentication in your script, it will be bound by the permission role assigned to you in Shotgun. For example, if you don't have access to edit the status field on Shots, your script won't be able to either. Attempting to perform actions that are prohibited by permissions will raise an appropriate exception. |
| 62 | +When using user-based authentication in your script, it will be bound by the permission role assigned to you in ShotGrid. For example, if you don't have access to edit the status field on Shots, your script won't be able to either. Attempting to perform actions that are prohibited by permissions will raise an appropriate exception. |
63 | 63 |
|
64 | | -.. seealso:: `Shotgun Support: Permissions <https://help.autodesk.com/view/SGSUB/ENU/?guid=SG_Administrator_ar_site_configuration_ar_permissions_html>`_ |
| 64 | +.. seealso:: `Permissions Documentation <https://help.autodesk.com/view/SGSUB/ENU/?guid=SG_Administrator_ar_site_configuration_ar_permissions_html>`_ |
65 | 65 |
|
0 commit comments