Gazer Philosophy

Philosophy

Gazer follows the traditional ideas about creating utilities in Unix. The commands are designed to do one specific task. The output of that Gazer command is usually in a format so that it can be easily fed into another Unix command. These building blocks can be assembled piece by piece into powerful integrations.

Example - Disabling Inactive Users

For example, one might want to programmatically disable users if they have not logged in for some period of time. This command will provide the information needed in a plain format.

gzr user ls --host=looker.example.com --fields=id,email --last-login --plain

Some of the users have no information about last login, so we can filter them out using grep. And then we can sort the list so we can see what users have gone the longest since the last login.

gzr user ls --host=looker.example.com --fields=id,email --last-login --plain | grep -v "^ " | sort -r

Filtering on that date value can be difficult, however, so we can use an awk script to do the filtering.

BEGIN {
    starttime = mktime(starttime)
    endtime = mktime(endtime)
}

func in_range(n, start, end) {
    return start <= n && n < end
}

match($0, /^([0-9]{4})-([0-9]{2})-([0-9]{2})\s/, m) &&
    in_range(mktime(m[1] " " m[2] " " m[3] " 00 00 00"), starttime, endtime)

We save this script as filter_dates.awk. Then we can run with the filter, use the cut utility to select out only the user id, and pass that user id to the command gzr user disable command using xargs.

gzr user ls --host=looker.example.com --fields=id,email --last-login --plain |\
  grep -v "^ " |\
  gawk -f filter_dates.awk  -v starttime='1970 00 00 00 00 00' -v endtime='2017 01 01 0 00 00' |\
  cut -c27-31 |\
  xargs -n 1 gzr user --host=looker.example.com disable

Controlling the Output

In order to make this easier there are several switches that can control the formatting of the output of many commands.

Plain

The --plain switch will make any command that normally returns a table of data return the table without lines drawn around the header, footer, and the columns.

CSV

The --csv switch will output data in RFC4180 csv format. It is important to note that RFC4180 specifies carriage returns and line feeds after each line. Unix systems usually use only line feeds.

The csv output will have a header line. If --csv --plain is specified, then the header line will be omitted.

Fields

The --fields=... switch specifies the fields that should be in the output. This is the same field list as used in the Looker API. So --fields=name1,name2,name3 will specify the fields name1, name2, and name3 from the top level of the JSON document returned by the API. If a field is nested, the it is specified as --fields=name1,group1(name2,name3),group2(subgroup3(name4).

Dir

Some commands will return a JSON document that describes the Looker object. The --dir=... command will save those JSON documents into files. Commonly the current directory is specified like --dir .. The files will be named in a standard pattern based on the type of object, the unique id of the object, and the name or title of the object. So if dashboard 371 is named "Monthly Profit", the file will be named Dashboard_371_Monthly Profit.json. Spaces and other special characters in the object name are not escaped in any way when making the file, so scripts that process these files should be carefully about quoting the filenames.

Running As an Alternate User

If you have an administrator account, you may wish to create or import content owned by another user. Gazer provides an easy way to change your session to that user's identity temporarily. Any command you run will then run as if that user was running it. The alternate user does not need to have API3 credentials setup.

In order to do this, simply use the switch --su=USER_ID. For example, the command gzr space create "New Space" 508 --host=looker.example.com --su=93 will create a new space named "New Space" in space 508, owned by user 93.