cis Package¶

`cis` Package¶

`tagging_client` Module¶

Copyright 2013-2014 VMware, Inc. All rights reserved. – VMware Confidential Copyright 2013-2014 VMware, Inc. All rights reserved. – VMware Confidential Copyright 2013-2014 VMware, Inc. All rights reserved. – VMware Confidential Copyright 2013-2014 VMware, Inc. All rights reserved. – VMware Confidential Copyright 2013-2014 VMware, Inc. All rights reserved. – VMware Confidential The com.vmware.cis.tagging_client component provides methods and classes to attach metadata, by means of tags, to vSphere objects to make these objects more sortable and searchable. You can use it to create, manage, and enumerate tags and their categories (the group a tag belongs to). You can also query the attached tags and attached objects.

class com.vmware.cis.tagging_client.Category(config)[source]¶

Bases: vmware.vapi.bindings.stub.VapiInterface

The Category class provides methods to create, read, update, delete, and enumerate categories.

Parameters:	config (`vmware.vapi.bindings.stub.StubConfiguration`) – Configuration to be used for creating the stub.

class CreateSpec(name=None, description=None, cardinality=None, associable_types=None)[source]¶

Bases: vmware.vapi.bindings.struct.VapiStruct

The Category.CreateSpec class is used to create a category.

Use the Category.create() method to create a category defined by the create specification.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:	name (`str`) – The display name of the category. description (`str`) – The description of the category. cardinality (`CategoryModel.Cardinality`) – The associated cardinality (SINGLE, MULTIPLE) of the category. associable_types (`set` of `str`) – Object types to which this category’s tags can be attached.

class Category.UpdateSpec(name=None, description=None, cardinality=None, associable_types=None)[source]¶

Bases: vmware.vapi.bindings.struct.VapiStruct

The Category.UpdateSpec class describes the updates to be made to an existing category.

Use the Category.update() method to modify a category. When you call the method, specify the category identifier. You obtain the category identifier when you call the Category.create() method. You can also retrieve an identifier by using the Category.list() method.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

name (str or None) – The display name of the category. If None the name will not be modified.
description (str or None) – The description of the category. If None the description will not be modified.
cardinality (CategoryModel.Cardinality or None) – The associated cardinality (SINGLE, MULTIPLE) of the category. If None the cardinality will not be modified.
associable_types (set of str or None) –
Object types to which this category’s tags can be attached.

The set of associable types cannot be updated incrementally. For example, if Category.UpdateSpec.associable_types originally contains {A,B,C} and you want to add D, then you need to pass {A,B,C,D} in your update specification. You also cannot remove any item from this set. For example, if you have {A,B,C}, then you cannot remove say {A} from it. Similarly, if you start with an empty set, then that implies that you can tag any object and hence you cannot later pass say {A}, because that would be restricting the type of objects you want to tag. Thus, associable types can only grow and not shrink. If None the associable types will not be modified.

Category.add_to_used_by(category_id, used_by_entity)[source]¶

Adds the used_by_entity to the CategoryModel.used_by subscribers set for the specified category. If the used_by_entity is already in the set, then this becomes an idempotent no-op. To invoke this method, you need the modify CategoryModel.used_by privilege on the category.

Parameters:	category_id (`str`) – The identifier of the input category. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`. used_by_entity (`str`) – The name of the user to be added to the `CategoryModel.used_by` `set`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to add an entity to the `CategoryModel.used_by` field.

Category.create(create_spec)[source]¶

Creates a category. To invoke this method, you need the create category privilege.

Parameters:	create_spec (`Category.CreateSpec`) – Specification for the new category to be created.
Return type:	`str`
Returns:	The identifier of the created category. The return value will be an identifier for the resource type: `com.vmware.cis.tagging.Category`.
Raise :	`com.vmware.vapi.std.errors_client.AlreadyExists` if the `Category.CreateSpec.name` provided in the `create_spec` is the name of an already existing category.
Raise :	`com.vmware.vapi.std.errors_client.InvalidArgument` if any of the information in the `create_spec` is invalid.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to create a category.

Category.delete(category_id)[source]¶

Deletes an existing category. To invoke this method, you need the delete privilege on the category.

Parameters:	category_id (`str`) – The identifier of category to be deleted. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to delete the category.

Category.get(category_id)[source]¶

Fetches the category information for the given category identifier. In order to view the category information, you need the read privilege on the category.

Parameters:	category_id (`str`) – The identifier of the input category. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`.
Return type:	`CategoryModel`
Returns:	The `CategoryModel` that corresponds to `category_id`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to read the category.

Category.list()[source]¶

Enumerates the categories in the system. To invoke this method, you need the read privilege on the individual categories. The list will only contain those categories for which you have read privileges.

Return type:	`list` of `str`
Returns:	The `list` of resource identifiers for the categories in the system. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Category`.

Category.list_used_categories(used_by_entity)[source]¶

Enumerates all categories for which the used_by_entity is part of the CategoryModel.used_by subscribers set. To invoke this method, you need the read privilege on the individual categories.

Parameters:	used_by_entity (`str`) – The field on which the results will be filtered.
Return type:	`list` of `str`
Returns:	The `list` of resource identifiers for the categories in the system that are used by `used_by_entity`. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Category`.

Category.remove_from_used_by(category_id, used_by_entity)[source]¶

Removes the used_by_entity from the CategoryModel.used_by subscribers set. If the used_by_entity is not using this category, then this becomes a no-op. To invoke this method, you need the modify CategoryModel.used_by privilege on the category.

Parameters:	category_id (`str`) – The identifier of the input category. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`. used_by_entity (`str`) – The name of the user to be removed from the `CategoryModel.used_by` `set`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to remove an entity from the `CategoryModel.used_by` field.

Category.revoke_propagating_permissions(category_id)[source]¶

Revokes all propagating permissions on the given category. You should then attach a direct permission with tagging privileges on the given category. To invoke this method, you need category related privileges (direct or propagating) on the concerned category.

Parameters:	category_id (`str`) – The identifier of the input category. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to revoke propagating permissions on the category.

Category.update(category_id, update_spec)[source]¶

Updates an existing category. To invoke this method, you need the edit privilege on the category.

Parameters:	category_id (`str`) – The identifier of the category to be updated. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`. update_spec (`Category.UpdateSpec`) – Specification to update the category.
Raise :	`com.vmware.vapi.std.errors_client.AlreadyExists` if the `Category.UpdateSpec.name` provided in the `update_spec` is the name of an already existing category.
Raise :	`com.vmware.vapi.std.errors_client.InvalidArgument` if any of the information in the `update_spec` is invalid.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to update the category.

class com.vmware.cis.tagging_client.CategoryModel(id=None, name=None, description=None, cardinality=None, associable_types=None, used_by=None)[source]¶

Bases: vmware.vapi.bindings.struct.VapiStruct

The CategoryModel class defines a category that is used to group one or more tags.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

id (str) – The unique identifier of the category. When clients pass a value of this class as a parameter, the attribute must be an identifier for the resource type: com.vmware.cis.tagging.Category. When methods return a value of this class as a return value, the attribute will be an identifier for the resource type: com.vmware.cis.tagging.Category.
name (str) – The display name of the category.
description (str) – The description of the category.
cardinality (CategoryModel.Cardinality) – The associated cardinality (SINGLE, MULTIPLE) of the category.
associable_types (set of str) – The types of objects that the tags in this category can be attached to. If the set is empty, then tags can be attached to all types of objects. This field works only for objects that reside in Inventory Service (IS). For non IS objects, this check is not performed today and hence a tag can be attached to any non IS object.
used_by (set of str) – The set of users that can use this category. To add users to this, you need to have the edit privilege on the category. Similarly, to unsubscribe from this category, you need the edit privilege on the category. You should not modify other users subscription from this set.

class Cardinality(string)[source]¶

Bases: vmware.vapi.bindings.enum.Enum

The CategoryModel.Cardinality class defines the number of tags in a category that can be assigned to an object.

Note

This class represents an enumerated type in the interface language definition. The class contains class attributes which represent the values in the current version of the enumerated type. Newer versions of the enumerated type may contain new values. To use new values of the enumerated type in communication with a server that supports the newer version of the API, you instantiate this class. See enumerated type description page.

Parameters:	string (`str`) – String value for the `Cardinality` instance.

MULTIPLE = Cardinality(string='MULTIPLE')¶: An object can be assigned several of the tags in this category. For example, if a category is “Server”, then different tags of this category would be “AppServer”, “DatabaseServer” and so on. In this case a VM object can be assigned more than one of the above tags and hence the cardinality of the associated category here is multiple.

SINGLE = Cardinality(string='SINGLE')¶: An object can only be assigned one of the tags in this category. For example, if a category is “Operating System”, then different tags of this category would be “Windows”, “Linux”, and so on. In this case a VM object can be assigned only one of these tags and hence the cardinality of the associated category here is single.

class com.vmware.cis.tagging_client.Tag(config)[source]¶

Bases: vmware.vapi.bindings.stub.VapiInterface

The Tag class provides methods to create, read, update, delete, and enumerate tags.

Parameters:	config (`vmware.vapi.bindings.stub.StubConfiguration`) – Configuration to be used for creating the stub.

class CreateSpec(name=None, description=None, category_id=None)[source]¶

Bases: vmware.vapi.bindings.struct.VapiStruct

The Tag.CreateSpec class describes a tag.

Use the Tag.create() method to create a tag defined by the create specification.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

name (str) – The display name of the tag. The name must be unique within its category.
description (str) – The description of the tag.
category_id (str) – The unique identifier of the parent category in which this tag will be created. When clients pass a value of this class as a parameter, the attribute must be an identifier for the resource type: com.vmware.cis.tagging.Category. When methods return a value of this class as a return value, the attribute will be an identifier for the resource type: com.vmware.cis.tagging.Category.

class Tag.UpdateSpec(name=None, description=None)[source]¶

Bases: vmware.vapi.bindings.struct.VapiStruct

The Tag.UpdateSpec class describes the updates to be made to an existing tag.

Use the Tag.update() method to modify a tag. When you call the method, you specify the tag identifier. You obtain the tag identifier when you call the Tag.create() method. You can also retrieve an identifier by using the Tag.list() method.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:	name (`str` or `None`) – The display name of the tag. If None the name will not be modified. description (`str` or `None`) – The description of the tag. If None the description will not be modified.

Tag.add_to_used_by(tag_id, used_by_entity)[source]¶

Adds the used_by_entity to the TagModel.used_by subscribers set. If the used_by_entity is already in the set, then this becomes a no-op. To invoke this method, you need the modify TagModel.used_by privilege on the tag.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`. used_by_entity (`str`) – The name of the user to be added to the `TagModel.used_by` `set`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to add an entity to the `TagModel.used_by` field.

Tag.create(create_spec)[source]¶

Creates a tag. To invoke this method, you need the create tag privilege on the input category.

Parameters:	create_spec (`Tag.CreateSpec`) – Specification for the new tag to be created.
Return type:	`str`
Returns:	The identifier of the created tag. The return value will be an identifier for the resource type: `com.vmware.cis.tagging.Tag`.
Raise :	`com.vmware.vapi.std.errors_client.AlreadyExists` if the `Tag.CreateSpec.name` provided in the `create_spec` is the name of an already existing tag in the input category.
Raise :	`com.vmware.vapi.std.errors_client.InvalidArgument` if any of the input information in the `create_spec` is invalid.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for in the given `create_spec` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to create tag.

Tag.delete(tag_id)[source]¶

Deletes an existing tag. To invoke this method, you need the delete privilege on the tag.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to delete the tag.

Tag.get(tag_id)[source]¶

Fetches the tag information for the given tag identifier. To invoke this method, you need the read privilege on the tag in order to view the tag info.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`.
Return type:	`TagModel`
Returns:	The `TagModel` that corresponds to `tag_id`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if the user does not have the privilege to read the tag.

Tag.list()[source]¶

Enumerates the tags in the system. To invoke this method, you need read privilege on the individual tags. The list will only contain tags for which you have read privileges.

Return type:	`list` of `str`
Returns:	The `list` of resource identifiers for the tags in the system. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Tag`.

Tag.list_tags_for_category(category_id)[source]¶

Enumerates all tags for the given category. To invoke this method, you need the read privilege on the given category and the individual tags in that category.

Parameters:	category_id (`str`) – The identifier of the input category. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Category`.
Return type:	`list` of `str`
Returns:	The `list` of resource identifiers for the tags in the given input category. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Tag`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the category for the given `category_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to read the category.

Tag.list_used_tags(used_by_entity)[source]¶

Enumerates all tags for which the used_by_entity is part of the TagModel.used_by subscribers set. To invoke this method, you need the read privilege on the individual tags.

Parameters:	used_by_entity (`str`) – The field on which the results will be filtered.
Return type:	`list` of `str`
Returns:	The `list` of resource identifiers for the tags in the system that are used by `used_by_entity`. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Tag`.

Tag.remove_from_used_by(tag_id, used_by_entity)[source]¶

Removes the used_by_entity from the TagModel.used_by subscribers set. If the used_by_entity is not using this tag, then this becomes a no-op. To invoke this method, you need modify TagModel.used_by privilege on the tag.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`. used_by_entity (`str`) – The name of the user to be removed from the `TagModel.used_by` `set`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to remove an entity from the `TagModel.used_by` field.

Tag.revoke_propagating_permissions(tag_id)[source]¶

Revokes all propagating permissions on the given tag. You should then attach a direct permission with tagging privileges on the given tag. To invoke this method, you need tag related privileges (direct or propagating) on the concerned tag.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to revoke propagating permissions on the tag.

Tag.update(tag_id, update_spec)[source]¶

Updates an existing tag. To invoke this method, you need the edit privilege on the tag.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`. update_spec (`Tag.UpdateSpec`) – Specification to update the tag.
Raise :	`com.vmware.vapi.std.errors_client.AlreadyExists` if the `Tag.UpdateSpec.name` provided in the `update_spec` is the name of an already existing tag in the same category.
Raise :	`com.vmware.vapi.std.errors_client.InvalidArgument` if any of the input information in the `update_spec` is invalid.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to update the tag.

class com.vmware.cis.tagging_client.TagAssociation(config)[source]¶

Bases: vmware.vapi.bindings.stub.VapiInterface

The TagAssociation class provides methods to attach, detach, and query tags.

Parameters:	config (`vmware.vapi.bindings.stub.StubConfiguration`) – Configuration to be used for creating the stub.

attach(tag_id, object_id)[source]¶

Attaches the given tag to the input object. To invoke this method, you need the attach tag privilege on the tag and the read privilege on the object.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`. object_id (`com.vmware.vapi.std_client.DynamicID`) – The identifier of the input object.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.InvalidArgument` if the input tag is not eligible to be attached to this object or if the `object_id` is not valid.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to attach the tag or do not have the privilege to read the concerned object. The tag needs to pass the cardinality and associability test in order to be eligible for attachment.

detach(tag_id, object_id)[source]¶

Detaches the tag from the given object. To invoke this method, you need the attach tag privilege on the tag and the read privilege on the object.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`. object_id (`com.vmware.vapi.std_client.DynamicID`) – The identifier of the input object.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to detach the tag or do not have the privilege to read the concerned object.

list_attachable_tags(object_id)[source]¶

Fetches the list of attachable tags for the given object, omitting the tags that have already been attached. Criteria for attachability is calculated based on tagging cardinality (CategoryModel.cardinality) and associability (CategoryModel.associable_types) constructs. To invoke this method, you need the read privilege on the input object. The list will only contain those tags for which you have read privileges.

Parameters:	object_id (`com.vmware.vapi.std_client.DynamicID`) – The identifier of the input object.
Return type:	`list` of `str`
Returns:	The `list` of tag identifiers that are eligible to be attached to the given object. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Tag`.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to read the object.

list_attached_objects(tag_id)[source]¶

Fetches the list of attached objects for the given tag. To invoke this method, you need the read privilege on the input tag. Only those objects for which you have read privileges will be returned.

Parameters:	tag_id (`str`) – The identifier of the input tag. The parameter must be an identifier for the resource type: `com.vmware.cis.tagging.Tag`.
Return type:	`list` of `com.vmware.vapi.std_client.DynamicID`
Returns:	The `list` of attached object identifiers.
Raise :	`com.vmware.vapi.std.errors_client.NotFound` if the tag for the given `tag_id` does not exist in the system.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to read the tag.

list_attached_tags(object_id)[source]¶

Fetches the list of tags attached to the given object. To invoke this method, you need the read privilege on the input object. The list will only contain those tags for which you have read privileges.

Parameters:	object_id (`com.vmware.vapi.std_client.DynamicID`) – The identifier of the input object.
Return type:	`list` of `str`
Returns:	The `list` of all tag identifiers that correspond to the tags attached to the given object. The return value will contain identifiers for the resource type: `com.vmware.cis.tagging.Tag`.
Raise :	`com.vmware.vapi.std.errors_client.Unauthorized` if you do not have the privilege to read the object.

class com.vmware.cis.tagging_client.TagModel(id=None, category_id=None, name=None, description=None, used_by=None)[source]¶

Bases: vmware.vapi.bindings.struct.VapiStruct

The TagModel class defines a tag that can be attached to vSphere objects.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

id (str) – The unique identifier of the tag. When clients pass a value of this class as a parameter, the attribute must be an identifier for the resource type: com.vmware.cis.tagging.Tag. When methods return a value of this class as a return value, the attribute will be an identifier for the resource type: com.vmware.cis.tagging.Tag.
category_id (str) – The identifier of the parent category in which this tag will be created. When clients pass a value of this class as a parameter, the attribute must be an identifier for the resource type: com.vmware.cis.tagging.Category. When methods return a value of this class as a return value, the attribute will be an identifier for the resource type: com.vmware.cis.tagging.Category.
name (str) – The display name of the tag.
description (str) – The description of the tag.
used_by (set of str) – The set of users that can use this tag. To add users to this, you need to have the edit privilege on the tag. Similarly, to unsubscribe from this tag, you need the edit privilege on the tag. You should not modify other users subscription from this set.

cis Package¶

`cis` Package¶

`tagging_client` Module¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

cis Package¶

cis Package¶

tagging_client Module¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation

`cis` Package¶

`tagging_client` Module¶