Skip to main content

groups

Creates, updates, deletes, gets or lists a groups resource.

Overview​

Namegroups
TypeResource
Idoci.identity.groups

Fields​

The following fields are returned by SELECT queries:

The group was retrieved.

NameDatatypeDescription
idstringThe OCID of the group.
namestringThe name you assign to the group during creation. The name must be unique across all groups in the tenancy and cannot be changed.
compartmentIdstringThe OCID of the tenancy containing the group.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
descriptionstringThe description you assign to the group. Does not have to be unique, and it's changeable. (For tenancies that support identity domains) You can have an empty description.
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
inactiveStatusinteger (int64)The detailed status of INACTIVE lifecycleState.
lifecycleStatestringThe group's current state. After creating a group, make sure its lifecycleState changes from CREATING to ACTIVE before using it. (CREATING, ACTIVE, INACTIVE, DELETING, DELETED)
timeCreatedstring (date-time)Date and time the group was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectgroupId, regionGets the specified group's information.<br /><br />This operation does not return a list of all the users in the group. To do that, use<br />[ListUserGroupMemberships](#/en/identity/20160918/UserGroupMembership/ListUserGroupMemberships) and<br />provide the group's OCID as a query parameter in the request.<br />
listselectcompartmentId, regionpage, limit, name, sortBy, sortOrder, lifecycleStateLists the groups in your tenancy. You must specify your tenancy's OCID as the value for<br />the compartment ID (remember that the tenancy is simply the root compartment).<br />See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).<br />
createinsertregion, name, compartmentId, descriptionopc-retry-tokenCreates a new group in your tenancy.<br /><br />You must specify your tenancy's OCID as the compartment ID in the request object (remember that the tenancy<br />is simply the root compartment). Notice that IAM resources (users, groups, compartments, and some policies)<br />reside within the tenancy itself, unlike cloud resources such as compute instances, which typically<br />reside within compartments inside the tenancy. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the group, which must be unique across all groups in your tenancy and<br />cannot be changed. You can use this name or the OCID when writing policies that apply to the group. For more<br />information about policies, see [How Policies Work](/Content/Identity/policieshow/how-policies-work.htm).<br /><br />You must also specify a description for the group (although it can be an empty string). It does not<br />have to be unique, and you can change it anytime with [UpdateGroup](#/en/identity/20160918/Group/UpdateGroup).<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the<br />object, first make sure its lifecycleState has changed to ACTIVE.<br /><br />After creating the group, you need to put users in it and write policies for it.<br />See [AddUserToGroup](#/en/identity/20160918/UserGroupMembership/AddUserToGroup) and<br />[CreatePolicy](#/en/identity/20160918/Policy/CreatePolicy).<br />
updateupdategroupId, regionif-matchUpdates the specified group.
deletedeletegroupId, regionif-matchDeletes the specified group. The group must be empty.<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe OCID of the compartment (remember that the tenancy is simply the root compartment).
groupIdstringThe OCID of the group.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerThe maximum number of items to return in a paginated "List" call.
namestringA filter to only return resources that match the given name exactly.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringThe value of the opc-next-page response header from the previous "List" call.
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for NAME is ascending. The NAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by Availability Domain if the scope of the resource type is within a single Availability Domain. If you call one of these "List" operations without specifying an Availability Domain, the resources are grouped by Availability Domain, then sorted.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC). The NAME sort order is case sensitive.

SELECT examples​

Gets the specified group's information.<br /><br />This operation does not return a list of all the users in the group. To do that, use<br />[ListUserGroupMemberships](#/en/identity/20160918/UserGroupMembership/ListUserGroupMemberships) and<br />provide the group's OCID as a query parameter in the request.<br />

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
timeCreated
FROM oci.identity.groups
WHERE groupId = '{{ groupId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new group in your tenancy.<br /><br />You must specify your tenancy's OCID as the compartment ID in the request object (remember that the tenancy<br />is simply the root compartment). Notice that IAM resources (users, groups, compartments, and some policies)<br />reside within the tenancy itself, unlike cloud resources such as compute instances, which typically<br />reside within compartments inside the tenancy. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the group, which must be unique across all groups in your tenancy and<br />cannot be changed. You can use this name or the OCID when writing policies that apply to the group. For more<br />information about policies, see [How Policies Work](/Content/Identity/policieshow/how-policies-work.htm).<br /><br />You must also specify a description for the group (although it can be an empty string). It does not<br />have to be unique, and you can change it anytime with [UpdateGroup](#/en/identity/20160918/Group/UpdateGroup).<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the<br />object, first make sure its lifecycleState has changed to ACTIVE.<br /><br />After creating the group, you need to put users in it and write policies for it.<br />See [AddUserToGroup](#/en/identity/20160918/UserGroupMembership/AddUserToGroup) and<br />[CreatePolicy](#/en/identity/20160918/Policy/CreatePolicy).<br />

INSERT INTO oci.identity.groups (
compartmentId,
definedTags,
description,
freeformTags,
name,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ description }}' /* required */,
'{{ freeformTags }}',
'{{ name }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
timeCreated
;

UPDATE examples​

Updates the specified group.

UPDATE oci.identity.groups
SET 
definedTags = '{{ definedTags }}',
description = '{{ description }}',
freeformTags = '{{ freeformTags }}'
WHERE 
groupId = '{{ groupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
timeCreated;

DELETE examples​

Deletes the specified group. The group must be empty.<br />

DELETE FROM oci.identity.groups
WHERE groupId = '{{ groupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;