Skip to content

Commit e1d0500

Browse files
jorwoodsjorwoods
authored
docs: document groupsets endpoint (#1767)
1 parent aeec396 commit e1d0500

1 file changed

Lines changed: 334 additions & 0 deletions

File tree

‎docs/api-ref.md‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2441,6 +2441,340 @@ job = server.groups.update(group, as_job=True)
24412441

24422442
---
24432443

2444+
## GroupSets
2445+
2446+
Using the TSC library, you can get information about all the group sets on a site, create or delete group sets, and add or remove groups from a group set.
2447+
2448+
The group set resources for Tableau Server are defined in the `GroupSetItem` class. The class corresponds to the group set resources you can access using the Tableau Server REST API. The group set methods are based upon the endpoints for group sets in the REST API and operate on the `GroupSetItem` class.
2449+
2450+
<br>
2451+
<br>
2452+
2453+
### GroupSetItem class
2454+
2455+
```py
2456+
GroupSetItem(name)
2457+
```
2458+
2459+
The `GroupSetItem` class contains the attributes for the group set resources on Tableau Server. The `GroupSetItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
2460+
2461+
Source file: models/groupset_item.py
2462+
2463+
**Attributes**
2464+
2465+
Name | Description
2466+
:--- | :---
2467+
`id` | The id of the group set.
2468+
`name` | The name of the group set. The `name` is required when you create an instance of a group set.
2469+
`groups` | The list of groups (`GroupItem`) that belong to this group set.
2470+
`group_count` | The number of groups in the group set.
2471+
2472+
**Example**
2473+
2474+
```py
2475+
new_groupset = TSC.GroupSetItem('My Group Set')
2476+
2477+
# call groupsets.create() with new group set
2478+
groupset = server.groupsets.create(new_groupset)
2479+
```
2480+
2481+
<br>
2482+
<br>
2483+
2484+
### GroupSets methods
2485+
2486+
The Tableau Server Client provides several methods for interacting with group set resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
2487+
2488+
Source file: server/endpoint/groupsets_endpoint.py
2489+
2490+
<br>
2491+
<br>
2492+
2493+
#### groupsets.get
2494+
2495+
```py
2496+
groupsets.get(req_options=None, result_level=None)
2497+
```
2498+
2499+
Returns information about the group sets on the specified site.
2500+
2501+
REST API: [Get Group Sets](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_sets)
2502+
2503+
**Version**
2504+
2505+
This endpoint is available with REST API version 3.22 and up.
2506+
2507+
**Parameters**
2508+
2509+
Name | Description
2510+
:--- | :---
2511+
`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. Filter parameters can include `page_size` and `page_number`.
2512+
`result_level` | (Optional) Specifies the level of detail in the response. Can be `"members"` to include member groups, or `"local"` for local group sets only.
2513+
2514+
**Returns**
2515+
2516+
Returns a list of `GroupSetItem` objects and a `PaginationItem` object.
2517+
2518+
**Example**
2519+
2520+
```py
2521+
all_groupsets, pagination_item = server.groupsets.get()
2522+
for groupset in all_groupsets:
2523+
print(groupset.id, groupset.name)
2524+
```
2525+
2526+
<br>
2527+
<br>
2528+
2529+
#### groupsets.get_by_id
2530+
2531+
```py
2532+
groupsets.get_by_id(groupset_id)
2533+
```
2534+
2535+
Returns information about the specified group set.
2536+
2537+
REST API: [Get Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_set)
2538+
2539+
**Version**
2540+
2541+
This endpoint is available with REST API version 3.22 and up.
2542+
2543+
**Parameters**
2544+
2545+
Name | Description
2546+
:--- | :---
2547+
`groupset_id` | The id of the group set.
2548+
2549+
**Returns**
2550+
2551+
Returns a `GroupSetItem` object.
2552+
2553+
**Example**
2554+
2555+
```py
2556+
groupset = server.groupsets.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
2557+
print(groupset.name)
2558+
```
2559+
2560+
<br>
2561+
<br>
2562+
2563+
#### groupsets.create
2564+
2565+
```py
2566+
groupsets.create(groupset_item)
2567+
```
2568+
2569+
Creates a new group set on the specified site.
2570+
2571+
REST API: [Create Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#create_group_set)
2572+
2573+
**Version**
2574+
2575+
This endpoint is available with REST API version 3.22 and up.
2576+
2577+
**Parameters**
2578+
2579+
Name | Description
2580+
:--- | :---
2581+
`groupset_item` | The `GroupSetItem` specifies the group set to add. You first create a new instance of a `GroupSetItem` and pass that to this method.
2582+
2583+
**Returns**
2584+
2585+
Returns the newly created `GroupSetItem` object.
2586+
2587+
**Example**
2588+
2589+
```py
2590+
new_groupset = TSC.GroupSetItem('My Group Set')
2591+
created_groupset = server.groupsets.create(new_groupset)
2592+
print(created_groupset.id)
2593+
```
2594+
2595+
<br>
2596+
<br>
2597+
2598+
#### groupsets.update
2599+
2600+
```py
2601+
groupsets.update(groupset_item)
2602+
```
2603+
2604+
Modifies an existing group set. You can use this method to rename a group set.
2605+
2606+
REST API: [Update Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group_set)
2607+
2608+
**Version**
2609+
2610+
This endpoint is available with REST API version 3.22 and up.
2611+
2612+
**Parameters**
2613+
2614+
Name | Description
2615+
:--- | :---
2616+
`groupset_item` | The `GroupSetItem` to update. The group set item must have a valid `id`.
2617+
2618+
**Returns**
2619+
2620+
Returns the updated `GroupSetItem` object.
2621+
2622+
**Example**
2623+
2624+
```py
2625+
groupset.name = 'Renamed Group Set'
2626+
updated_groupset = server.groupsets.update(groupset)
2627+
```
2628+
2629+
<br>
2630+
<br>
2631+
2632+
#### groupsets.delete
2633+
2634+
```py
2635+
groupsets.delete(groupset)
2636+
```
2637+
2638+
Deletes the specified group set from the site.
2639+
2640+
REST API: [Delete Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#delete_group_set)
2641+
2642+
**Version**
2643+
2644+
This endpoint is available with REST API version 3.22 and up.
2645+
2646+
**Parameters**
2647+
2648+
Name | Description
2649+
:--- | :---
2650+
`groupset` | The `GroupSetItem` or group set id (`str`) to delete.
2651+
2652+
**Returns**
2653+
2654+
None.
2655+
2656+
**Example**
2657+
2658+
```py
2659+
server.groupsets.delete(groupset.id)
2660+
```
2661+
2662+
<br>
2663+
<br>
2664+
2665+
#### groupsets.add_group
2666+
2667+
```py
2668+
groupsets.add_group(groupset_item, group)
2669+
```
2670+
2671+
Adds a group to the specified group set.
2672+
2673+
REST API: [Add Group to Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#add_group_to_group_set)
2674+
2675+
**Version**
2676+
2677+
This endpoint is available with REST API version 3.22 and up.
2678+
2679+
**Parameters**
2680+
2681+
Name | Description
2682+
:--- | :---
2683+
`groupset_item` | The `GroupSetItem` specifying the group set to update.
2684+
`group` | The `GroupItem` or group id (`str`) to add to the group set.
2685+
2686+
**Returns**
2687+
2688+
None.
2689+
2690+
**Example**
2691+
2692+
```py
2693+
all_groups, _ = server.groups.get()
2694+
mygroup = all_groups[0]
2695+
2696+
server.groupsets.add_group(groupset, mygroup)
2697+
```
2698+
2699+
<br>
2700+
<br>
2701+
2702+
#### groupsets.remove_group
2703+
2704+
```py
2705+
groupsets.remove_group(groupset_item, group)
2706+
```
2707+
2708+
Removes a group from the specified group set.
2709+
2710+
REST API: [Remove Group from Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#remove_group_from_group_set)
2711+
2712+
**Version**
2713+
2714+
This endpoint is available with REST API version 3.22 and up.
2715+
2716+
**Parameters**
2717+
2718+
Name | Description
2719+
:--- | :---
2720+
`groupset_item` | The `GroupSetItem` specifying the group set to update.
2721+
`group` | The `GroupItem` or group id (`str`) to remove from the group set.
2722+
2723+
**Returns**
2724+
2725+
None.
2726+
2727+
**Example**
2728+
2729+
```py
2730+
server.groupsets.remove_group(groupset, mygroup)
2731+
```
2732+
2733+
<br>
2734+
<br>
2735+
2736+
#### groupsets.filter
2737+
2738+
```py
2739+
groupsets.filter(**kwargs)
2740+
```
2741+
2742+
Returns a list of group sets that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
2743+
2744+
**Version**
2745+
2746+
This endpoint is available with REST API version 3.22 and up.
2747+
2748+
**Supported fields and operators**
2749+
2750+
Field | Operators
2751+
:--- | :---
2752+
`domain_name` | `eq`, `in`
2753+
`domain_nickname` | `eq`, `in`
2754+
`is_external_user_enabled` | `eq`
2755+
`is_local` | `eq`
2756+
`luid` | `eq`, `in`
2757+
`minimum_site_role` | `eq`, `in`
2758+
`name` | `eq`, `cieq`, `in`, `like`
2759+
`user_count` | `eq`, `gt`, `gte`, `lt`, `lte`
2760+
2761+
**Returns**
2762+
2763+
Returns a `QuerySet` of `GroupSetItem` objects.
2764+
2765+
**Example**
2766+
2767+
```py
2768+
local_groupsets = server.groupsets.filter(is_local=True)
2769+
for groupset in local_groupsets:
2770+
print(groupset.name)
2771+
```
2772+
2773+
<br>
2774+
<br>
2775+
2776+
---
2777+
24442778
## Jobs
24452779

24462780
Using the TSC library, you can get information about an asynchronous process (or *job*) on the server. These jobs can be created when Tableau runs certain tasks that could be long running, such as importing or synchronizing users from Active Directory, or running an extract refresh. For example, the REST API methods to create or update groups, to run an extract refresh task, or to publish workbooks can take an `asJob` parameter (`asJob-true`) that creates a background process (the *job*) to complete the call. Information about the asynchronous job is returned from the method.

0 commit comments

Comments
 (0)