GoogleDriveManagement/docs/Users-DataStudio.md

Users - Data Studio

• API documentation
• Notes
• Definitions
• Display Data Studio assets
• Manage Data Studio permissions
  • Add Permissions
  • Delete Permissions
  • Update Permissions
• Display Data Studio permissions

API documentation

• https://developers.google.com/datastudio/api/reference

Notes

To use these commands you must add the 'Data Studio API' to your project and update your service account authorization.

gam update project
gam user user@domain.com check serviceaccount

Definitions

• <UserTypeEntity>

<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= id:<String>
<UserItem> ::= <EmailAddress>|<UniqueID>|<String>

<DataStudioAssetID> ::= <String>
<DataStudioAssetIDList> ::= "<DataStudioAssetID>(,<DataStudioAssetID>)*"
<DataStudioAssetIDEntity> ::=
        <DataStudioAssetIDList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>

<DataStudioPermission> ::=
        user:<EmailAddress>|
        group:<EmailAddress>|
        domain:<DomainName>|
        serviceAccount:<EmailAddress>
<DataStudioPermissionList> ::= "<DataStudioPermission>(,<DataStudioPermission>)*"
<DataStudioPermissionEntity> ::=
        <DataStudioPermissionList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>

Data Studio assets have an ID that is referred to by Google as its name; this is the value you will use wherever <DataStudioAssetID> is required.

Display Data Studio assets

gam <UserTypeEntity> show datastudioassets
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity>)]
        [stripcrsfromtitle]
        [formatjson]

By default, all assets of type report not in the trash are displayed; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Display assets with the specified assettype
  • title <String> - Display assets with the specified title
  • owner <Emailddress> - Display assets with the specified owner
  • includetrashed - Display assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Display a specific list of assetids

The stripcrsfromtitle option strips nulls, carriage returns and linefeeds from asset titles. Use this option if you discover asset titles containing these special characters; it is not common.

By default, Gam displays the information as an indented list of keys and values.

• formatjson - Display the fields in JSON format.

gam <UserTypeEntity> print datastudioassets [todrive <ToDriveAttribute>*]
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity>)]
        [stripcrsfromtitle]
        [formatjson [quotechar <Character>]]

By default, all assets of type report not in the trash are displayed; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Display assets with the specified assettype
  • title <String> - Display assets with the specified title
  • owner <Emailddress> - Display assets with the specified owner
  • includetrashed - Display assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Display a specific list of assetids

The stripcrsfromtitle option strips nulls, carriage returns and linefeeds from asset titles. Use this option if you discover asset titles containing these special characters; it is not common.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Manage Data Studio permissions

• The owner of an asset can not have it's role changed.
• The owner of an asset can not be deleted.
• A new owner can not be added to an asset.

<EmailAddress> in <DataStudioPermission> must be complete, GAM will not add a domain name.

A viewer can not manage permissions.

Add permissions

gam <UserTypeEntity> add datastudiopermissions
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity)]
        (role editor|viewer <DataStudioPermissionEntity>)+
        [nodetails]

By default, the permission is added to all assets of type report not in the trash; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Add permission to assets with the specified assettype
  • title <String> - Add permission to assets with the specified title
  • owner <Emailddress> - Add permission to assets with the specified owner
  • includetrashed - Add permission to assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Add permission to a specific list of assetids

By default, when a permission is added, GAM outputs details of the permission. The nodetails option suppresses this output.

Delete permissions

gam <UserTypeEntity> delete datastudiopermissions
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity)]
        (role any <DataStudioPermissionEntity>)+
        [nodetails]

By default, the permission is deleted from all assets of type report not in the trash; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Delete permission from assets with the specified assettype
  • title <String> - Delete permission from assets with the specified title
  • owner <Emailddress> - Delete permission from assets with the specified owner
  • includetrashed - Delete permission from assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Delete permission from a specific list of assetids

By default, when a permission is deleted, GAM outputs details of the permission. The nodetails option suppresses this output.

Update permissions

A permission is updated by deleting the existing permission and then adding the new permission.

gam <UserTypeEntity> update datastudiopermissions
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity)]
        (role editor|viewer <DataStudioPermissionEntity>)+
        [nodetails]

By default, the permission is updated in all assets of type report not in the trash; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Update permission in assets with the specified assettype
  • title <String> - Update permission in assets with the specified title
  • owner <Emailddress> - Update permission in assets with the specified owner
  • includetrashed - Update permission in assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Update permission in a specific list of assetids

By default, when a permission is updated, GAM outputs details of the permission. The nodetails option suppresses this output.

Display Data Studio permissions

A viewer can not display permissions.

gam <UserTypeEntity> show datastudiopermissions
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity>)]
        [role editor|owner|viewer]
        [formatjson]

By default, permissions for all assets of type report not in the trash are displayed; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Display permissions for assets with the specified assettype
  • title <String> - Display permissions for assets with the specified title
  • owner <Emailddress> - Display permissions for assets with the specified owner
  • includetrashed - Display permissions for assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Display permissions for a specific list of assetids

The Data Studio API defines this parameter role editor|owner|viewer but it doesn't seem to have any effect.

By default, Gam displays the information as an indented list of keys and values.

• formatjson - Display the fields in JSON format.

gam <UserTypeEntity> print datastudiopermissions [todrive <ToDriveAttribute>*]
        [([assettype report|datasource|all] [title <String>]
          [owner <Emailddress>] [includetrashed]
          [orderby title [ascending|descending]]) |
         (assetids <DataStudioAssetIDEntity>)]
        [role editor|owner|viewer]
        [formatjson [quotechar <Character>]]

By default, permissions for all assets of type report not in the trash are displayed; use the following options to select a subset of assets.

• Search
  • assettype report|datasource|all - Display permissions for assets with the specified assettype
  • title <String> - Display permissions for assets with the specified title
  • owner <Emailddress> - Display permissions for assets with the specified owner
  • includetrashed - Display permissions for assets in the trash
  • orderby title [ascending|descending] - Order of assets
• Specific
  • assetids <DataStudioAssetIDEntity> - Display permissions for a specific list of assetids

The Data Studio API defines this parameter role editor|owner|viewer but it doesn't seem to have any effect.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.