Articles, Blog

Developer Training – Shotgun: Interacting with the Shotgun API & CRUD


There are several sets of methods in the Shotgun Python API. In this video we will focus on the most useful methods in the CRUD set. CRUD stands for Creat, Read, Update and Delete. By the end of this video you will know how to create a Shot and Shotgun find an existing Shot and it details, Updated Shot and Deleted Shot. First I’ll create a new Project where we can test our CRUD api commands. Although these commands could apply to any entity in Shotgun, I’m going to focus on Shots. Let’s review how users create, update, and delete Shots from the Shotgun GUI. Notice that the Project field has already been populated with the current Project. We can modify that field value or other fields before creating the Shot. Fields in bold are required. Some required fields are arbitrary and can be managed by your Shotgun administrator, while others, like the Project field in this case, are required no matter what. So that was a CREATE action. I can now modify existing Shot field values. Those were UPDATE actions. Finally, I can remove the Shot record. That was a DELETE action. Note that nothing is ever truly deleted from Shotgun. Entity records are simply sent to the Trash and can be recovered. Next, we’ll repeat these actions from the API. Now, let’s create a Shot with the API. The create command requires at least two arguments. The name of the entity type, which is “Shot”, and a dictionary of field key/value pairs where the key is the internal name of the field. We know from our experience in the GUI that the “Project” and “Shot Code” fields are both required, so let’s specify values for those fields. If we don’t, the command may fail. If you don’t know the internal field name, check Shotgun. In this case, the field with a Display Name of “Shot Code” has an internal name of “code”. The field with a display name of capital­P Project has an internal name of lowercase­p project. It should now be clear that we don’t have enough information to complete the query. We don’t have the Project field value. So let’s backtrack a bit and use the find_one command to read the Project record from Shotgun. The find_one command requires at least two arguments. The name of the entity type, and a list of filters. Each filter is itself a list containing three items: the field name, a relationship, and a value. Note that the value in the filter is case insensitive. I can type CRUD with either upper or lowercase letters. Now that we’ve got the Project record, we can try our create command again. Let’s check Shotgun to see the result. Use the Shotgun find and find_one commands to read information from Shotgun. We’ve already seen the find one command in action, here we’ll use it to pull down our Project record again. Let’s dig in a little deeper. Let’s use the find command to query for an existing Shot and retrieve its Status and Description values. Here’s the Shot in Shotgun I’m going to target. Oops, it looks like there are two Shot records on our Site called “sh001”. So what do we do? Well, we could use a find_one command to limit our result to a single record, but there’s no guarantee that the record is the one we want. Instead, let’s add another filter to narrow the search criteria. This time we’ll only look for Shot records called “sh001” that are also in the Project “CRUD”. Great. That other “sh001” Shot record must have been in another Project. Once you’re confident that only one result will be returned, you can switch to the find_one command. It’s more efficient and a little easier to work with since it doesn’t return a list. But the takeaway is: if you’re at all worried that multiple records could match your query, use the find method instead of find_one and check the result before proceeding. OK, so now we have a shot. By default, the API returns dictionary with the entity type and id field data. This is the minimum amount of information Shotgun needs to identify an entity record in the database. That’s all well and good, but we want to know what this Shot’s Status is, and its description. So-to include specific fields that aren’t returned by default- add the third argument, which is a list of internal field names. If you don’t know the internal field name, check Shotgun. In this case, the Display Name of the first field we want to return is Status, and the internal name is sg_stautus_list. Let’s do the same thing to return the value in the description field. Success! Now let’s use the find command instead of the find_one command to retrieve ALL Shots attached to our Project. Here is our list of Shots. And just like with the find_one command, a third list argument can be added to the query to retrieve specific field values. You can also find a field’s internal name by visiting the fields page. Use the update command to change field values on existing records in Shotgun. Let’s use the update command to attach all the Shots in our Project to a new Sequence named “seq001”, and change their Status values to “Ready to Start”. First we’ll need our Project record. Once we have that, we can create a new Sequence record. Next, let’s find the Shot records we want to update. Now we can loop over those Shots and run our update command. To update an entity record, we’ll need the entity type and it’s id. After that it’s a simple matter of specifying a dictionary of key/value pairs where the key is an internal field name. So let’s update the sg_status_list value to “Ready To Start”, and the sg_sequence value to our new seq001 Sequence. Let’s check Shotgun to see the result. Use the delete command to send existing records to the Trash. Let’s use the delete command to remove all Shot records from our Project. First we’ll need our Project record. Next we need to grab the list of Shots we want to delete and loop over it. The delete command takes two arguments: the entity type, and its ID. Let’s check Shotgun to see the result. Remember that you can revive entity records that were deleted at any point in the future. The revive command takes the same two arguments as the delete command. Note that the Sequence link is still intact. Complete documentation is available for the CRUD methods in the Shotgun Python API docs.

1 thought on “Developer Training – Shotgun: Interacting with the Shotgun API & CRUD

Leave a Reply

Your email address will not be published. Required fields are marked *