Apache Ranger Java APIs¶
Apache Ranger provides Java library to interact with the Ranger service. This API reference provides detailed information about the Java APIs. The Java library internally invoke the Apache Ranger REST APIs.
There are few examples in the user guide.
Key Features supported by the APIs:
- Service Definition: Define and manage services (e.g., Snowflake, Databricks Unity Catalog, AWS S3, etc) within Ranger.
- Policy Administration: Create, update, and delete policies (e.g., access control rules) for services.
- Resource Management: Manage resources (e.g., files, tables, topics) within services.
- User and Group Management: Manage users and groups within the Ranger system.
Constructors for RangerClient¶
Constructor for RangerClient using SSL configuration¶
public RangerClient(String hostName, String authType, String username, String password, String configFile)
This constructor initializes the RangerClient with the specified parameters. It creates a new instance of RangerRESTClient using the provided hostname and config file, and then initializes authentication based on the provided auth type, username, and password.
- Parameters:
hostName
— hostname of RangerauthType
— auth type - Basic, Kerberos etcusername
— usernamepassword
— passwordconfigFile
— path to config file for self-signed SSL enabled Apache Ranger
Constructor for RangerClient using Service Type¶
public RangerClient(String hostname, String authType, String username, String password, String appId, String serviceType)
This constructor initializes the RangerClient with the specified parameters. It creates a new instance of RangerRESTClient using the provided hostname and config file, and then initializes authentication based on the provided auth type, username, and password. The SSL configuration file is determined by the RangerPluginConfig based on the service type.
- Parameters:
hostname
— hostname of RangerauthType
— auth type - Basic, Kerberos etcusername
— username for connecting to Rangerpassword
— passwordappId
— application IdserviceType
— Ranger plugin service type e.g : s3, hive, hdfs etc
Constructor for RangerClient using RangerRESTClient¶
This constructor initializes the RangerClient with an existing instance of RangerRESTClient. It allows the user to provide a pre-configured RangerRESTClient, which can be useful for testing or when the RangerRESTClient needs to be customized before being used by RangerClient.- Parameters:
restClient
— - Ranger REST Client
Service Definition APIs¶
Create a new service definition in Apache Ranger¶
public RangerServiceDef createServiceDef(RangerServiceDef serviceDef) throws RangerServiceException`
This method sends a POST request to the Ranger Admin server to create a new service definition. The service definition is specified by the RangerServiceDef
object passed as a parameter. If the creation is successful, the method returns the created RangerServiceDef
object. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
serviceDef
— Service Definition
-
Returns:
- RangerServiceDef
-
Exceptions:
RangerServiceException
Update an existing service definition¶
public RangerServiceDef updateServiceDef(long serviceDefId, RangerServiceDef serviceDef) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing service definition. The service definition to be updated is identified by the serviceDefId
parameter, and the new service definition details are provided in the serviceDef
parameter. If the update is successful, the method returns the updated RangerServiceDef
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceDefId
— service definition idserviceDef
— new service definition
- Returns:
RangerServiceDef
- Exceptions:
RangerServiceException
Update an existing service definition¶
public RangerServiceDef updateServiceDef(String serviceDefName, RangerServiceDef serviceDef) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing service definition. The service definition to be updated is identified by the serviceDefName
parameter, and the new service definition details are provided in the serviceDef
parameter. If the update is successful, the method returns the updated RangerServiceDef
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceDefName
— service definition nameserviceDef
— new service definition
- Returns:
- updated RangerServiceDef
- Exceptions:
RangerServiceException
Delete a service definition by ID¶
This method sends a DELETE request to the Ranger Admin server to delete an existing service definition. The service definition to be deleted is identified by the serviceDefId
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceDefId
— the ID of the service definition to be deleted- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a service definition by name¶
This method sends a DELETE request to the Ranger Admin server to delete an existing service definition. The service definition to be deleted is identified by the serviceDefName
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceDefName
— the name of the service definition to be deleted- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a service definition by ID¶
This method sends a GET request to the Ranger Admin server to retrieve an existing service definition. The service definition to be retrieved is identified by the serviceDefId
parameter. If the retrieval is successful, the method returns the retrieved RangerServiceDef
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceDefId
— the ID of the service definition to be retrieved- Returns:
- The retrieved
RangerServiceDef
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a service definition by name¶
plaintext title="" linenums="0" public RangerServiceDef getServiceDef(String serviceDefName) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to retrieve an existing service definition. The service definition to be retrieved is identified by the serviceDefName
parameter. If the retrieval is successful, the method returns the retrieved RangerServiceDef
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceDefName
— the name of the service definition to be retrieved- Returns:
- The retrieved
RangerServiceDef
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Find service definitions based on filter criteria¶
public List<RangerServiceDef> findServiceDefs(Map<String, String> filter) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to find service definitions that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter
parameter. If the retrieval is successful, the method returns a list of matching RangerServiceDef
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
filter
— a map of key-value pairs representing the filter criteria- Returns:
- A list of matching
RangerServiceDef
objects - Exceptions:
RangerServiceException
— If an error occurs during the API call
Create a new service in Apache Ranger¶
This method sends a POST request to the Ranger Admin server to create a new service. The service details are provided in the service
parameter. If the creation is successful, the method returns the created RangerService
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
service
— the service details to be created- Returns:
- The created
RangerService
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing service by ID¶
plaintext title="" linenums="0" public RangerService updateService(long serviceId, RangerService service) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing service. The service to be updated is identified by the serviceId
parameter, and the new service details are provided in the service
parameter. If the update is successful, the method returns the updated RangerService
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceId
— the ID of the service to be updatedservice
— the new service details
- Returns:
- The updated
RangerService
object
- The updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing service by name¶
plaintext title="" linenums="0" public RangerService updateService(String serviceName, RangerService service) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing service. The service to be updated is identified by the serviceName
parameter, and the new service details are provided in the service
parameter. If the update is successful, the method returns the updated RangerService
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the service to be updatedservice
— the new service details
- Returns:
- The updated
RangerService
object
- The updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a service by ID¶
This method sends a DELETE request to the Ranger Admin server to delete an existing service. The service to be deleted is identified by the serviceId
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceId
— the ID of the service to be deleted- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a service by name¶
This method sends a DELETE request to the Ranger Admin server to delete an existing service. The service to be deleted is identified by the serviceName
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the service to be deleted
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a service by ID¶
This method sends a GET request to the Ranger Admin server to retrieve an existing service. The service to be retrieved is identified by the serviceId
parameter. If the retrieval is successful, the method returns the retrieved RangerService
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceId
— the ID of the service to be retrieved
- Returns:
- The retrieved
RangerService
object
- The retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a service by name¶
This method sends a GET request to the Ranger Admin server to retrieve an existing service. The service to be retrieved is identified by theserviceName
parameter. If the retrieval is successful, the method returns the retrieved RangerService
object. If an error occurs during the API call, a RangerServiceException
is thrown. - Parameters:
serviceName
— the name of the service to be retrieved
- Returns:
- The retrieved
RangerService
object
- The retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Find services based on filter criteria¶
This method sends a GET request to the Ranger Admin server to find services that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in thefilter
parameter. If the retrieval is successful, the method returns a list of matching RangerService
objects. If an error occurs during the API call, a RangerServiceException
is thrown. - Parameters:
filter
— a map of key-value pairs representing the filter criteria
- Returns:
- A list of matching
RangerService
objects
- A list of matching
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Policy APIs¶
Create a new policy in Apache Ranger¶
This method sends a POST request to the Ranger Admin server to create a new policy. The policy details are provided in the policy
parameter. If the creation is successful, the method returns the created RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policy
— the policy details to be created
- Returns:
- The created
RangerPolicy
object
- The created
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing policy by ID¶
This method sends a PUT request to the Ranger Admin server to update an existing policy. The policy to be updated is identified by thepolicyId
parameter, and the new policy details are provided in the policy
parameter. If the update is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown. - Parameters:
policyId
— the ID of the policy to be updatedpolicy
— the new policy details
- Returns:
- The updated
RangerPolicy
object
- The updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing policy by name¶
public RangerPolicy updatePolicy(String serviceName, String policyName, RangerPolicy policy) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing policy. The policy to be updated is identified by the serviceName
and policyName
parameters, and the new policy details are provided in the policy
parameter. If the update is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicepolicyName
— the name of the policy to be updatedpolicy
— the new policy details
- Returns:
- The updated
RangerPolicy
object
- The updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing policy by name and security zone¶
public RangerPolicy updatePolicyByNameAndZone(String serviceName, String policyName, String zoneName, RangerPolicy policy) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing policy. The policy to be updated is identified by the serviceName
, policyName
, and zoneName
parameters, and the new policy details are provided in the policy
parameter. If the update is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicepolicyName
— the name of the policy to be updatedzoneName
— the name of the Security zonepolicy
— the new policy details
- Returns:
- The updated
RangerPolicy
object
- The updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Apply a policy to the service¶
This method sends a POST request to the Ranger Admin server to apply a policy to the service. The policy to be applied is provided in the policy
parameter. If the application is successful, the method returns the applied RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policy
— the policy to be applied
- Returns:
- The applied
RangerPolicy
object
- The applied
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a policy by ID¶
This method sends a DELETE request to the Ranger Admin server to delete an existing policy. The policy to be deleted is identified by the policyId
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be deleted
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a policy by name¶
This method sends a DELETE request to the Ranger Admin server to delete an existing policy. The policy to be deleted is identified by the serviceName
and policyName
parameters. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicepolicyName
— the name of the policy to be deleted
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a policy by name and security zone¶
plaintext title="" linenums="0" public void deletePolicyByNameAndZone(String serviceName, String policyName, String zoneName) throws RangerServiceException`
This method sends a DELETE request to the Ranger Admin server to delete an existing policy. The policy to be deleted is identified by the serviceName
, policyName
, and zoneName
parameters. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicepolicyName
— the name of the policy to be deletedzoneName
— the name of the Security zone
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a policy by ID¶
This method sends a GET request to the Ranger Admin server to retrieve an existing policy. The policy to be retrieved is identified by the policyId
parameter. If the retrieval is successful, the method returns the retrieved RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be retrieved
- Returns:
- the retrieved
RangerPolicy
object
- the retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a policy by name¶
This method sends a GET request to the Ranger Admin server to retrieve an existing policy. The policy to be retrieved is identified by the serviceName
and policyName
parameters. If the retrieval is successful, the method returns the retrieved RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicepolicyName
— the name of the policy to be retrieved
- Returns:
- the retrieved
RangerPolicy
object
- the retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a policy by policy name and security zone name¶
public RangerPolicy getPolicyByNameAndZone(String serviceName, String policyName, String zoneName) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to retrieve an existing policy. The policy to be retrieved is identified by the serviceName
, policyName
, and zoneName
parameters. If the retrieval is successful, the method returns the retrieved RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicepolicyName
— the name of the policy to be retrievedzoneName
— the name of the Security zone
- Returns:
- the retrieved
RangerPolicy
object
- the retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve all policies for a service¶
This method sends a GET request to the Ranger Admin server to retrieve all policies for a service. The service is identified by the serviceName
parameter. If the retrieval is successful, the method returns a list of RangerPolicy
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the service
- Returns:
- A list of
RangerPolicy
objects
- A list of
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Find policies based on filter criteria¶
This method sends a GET request to the Ranger Admin server to find policies that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter
parameter. If the retrieval is successful, the method returns a list of matching RangerPolicy
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
filter
— a map of key-value pairs representing the filter criteria
- Returns:
- A list of matching
RangerPolicy
objects
- A list of matching
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Grant access to principals for resources defined in a policy identified by the policy ID.¶
public RangerPolicy grantAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isAllowException) throws RangerServiceException`
This method sends a POST request to the Ranger Admin server to grant access within an existing policy. The policyId
parameter specifies the target policy, while policyItems
defines the access permissions and associated principals. If the specified principals already have some permissions, the new ones will be appended. If isAllowException
parameter is set to true, the method updates the allowExceptions
section of the policy instead. On success, the updated RangerPolicy object is returned. If the new policy item has properties that conflict with an existing policy for the same principal, the API will raise an exception.
- Parameters:
policyId
— the ID of the policy to be updatedpolicyItems
— the access details to be grantedisAllowException
- if true, thepolicyItems
will be added to theallowExceptions
section within the policy
- Returns:
- the updated
RangerPolicy
object
- the updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update access to principals in a policy identified by the policy ID.¶
public RangerPolicy updateAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isAllowException) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update access to a policy. The policy to be updated is identified by the policyId
parameter, and the access details, along with the principals, are provided in the policyItems
parameter. If permissions already exist for the principals, the new ones will replace the existing ones, including the policy conditions for the same. If isAllowException
is true, the policyItems
will be added to the allowExceptions
section within the policy. If the update is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be updatedpolicyItems
— the access details to be updatedisAllowException
- if true, thepolicyItems
will be added to theallowExceptions
section within the policy
- Returns:
- the updated
RangerPolicy
object
- the updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete access to principals for resources defined in a policy identified by the policy ID.¶
public void deleteAccess(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap, List<String> permissions, boolean isAllowException) throws RangerServiceException
This method sends a DELETE request to the Ranger Admin server to delete access to a policy. The policy to be updated is identified by the policyId
parameter, and the principals are provided in the rangerPrincipalsMap
parameter. If isAllowException
is true, the principals will be removed from the allowExceptions
section within the policy. To delete specific permissions, add them to the permissions
list parameter. If the permission
list is empty, the principal will be removed completely from the policy items. If the deletion is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be updatedrangerPrincipalsMap
— the access principals for whom the access needs to be deleted.permissions
- List of permissions to be deleted for the given principals in therangerPrincipalsMap
isAllowException
- if true, the principals will be removed from theallowExceptions
section within the policy
- Returns:
- the updated
RangerPolicy
object without the principals for whom the access was deleted - Exceptions:
RangerServiceException
— If an error occurs during the API call
Deny access to principals for resources defined in a policy identified by the policy ID.¶
public RangerPolicy denyAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isDenyException) throws RangerServiceException`
This method sends a POST request to the Ranger Admin server to add deny access to a policy. The policy to be updated is identified by the policyId
parameter, and the access details, along with the principals, are provided in the policyItems
parameter. If permissions already exist for the principals, the new ones will be added to the same. If isDenyException
is true, the policyItems
will be added to the denyExceptions
section within the policy. If the update is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be updatedpolicyItems
— the access details to be deniedisDenyException
- if true, thepolicyItems
will be added to thedenyExceptions
section within the policy
- Returns:
- the updated
RangerPolicy
object
- the updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update deny access to principals for resources defined in a policy identified by the policy ID.¶
public RangerPolicy updateDenyAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isDenyException) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update deny access within a policy. The policy to be updated is identified by the policyId
parameter, and the access details, along with the principals, are provided in the policyItems
parameter. If permissions already exist for the principals, the new ones will replace the existing ones. If isDenyException
is true, the policyItems
will be added to the denyExceptions
section within the policy. If the update is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be updatedpolicyItems
— the access details to be updatedisDenyException
- if true,denyExceptions
section within the policy will be updated
- Returns:
- the updated
RangerPolicy
object
- the updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete deny access to principals for resources defined in a policy identified by the policy ID.¶
public void deleteDenyAccess(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap, List<String> permissions, boolean isDenyException) throws RangerServiceException`
This method sends a DELETE request to the Ranger Admin server to delete deny access within a policy. The policy to be updated is identified by the policyId
parameter, while the principals are provided in the rangerPrincipalsMap
parameter. If isDenyException
is true, the principals will be removed from the denyExceptions
section within the policy. To delete specific permissions, add them to the permissions
list parameter. If the permission
list is empty, the principal will be removed completely from the policy items. If the deletion is successful, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
policyId
— the ID of the policy to be updatedrangerPrincipalsMap
— the principals for whom the deny access needs to be deletedpermissions
- List of permissions to be deleted from the given principals in therangerPrincipalsMap
isDenyException
- if true,denyExceptions
section within the policy will be updated
- Returns:
- The updated
RangerPolicy
object without the principals for whom the deny access was deleted - Exceptions:
RangerServiceException
— If an error occurs during the API call
Add Data Masking Policy Items to an Existing Policy¶
public RangerPolicy addDataMaskPolicyItems(long policyId, List<RangerPolicy.RangerDataMaskPolicyItem> policyItems) throws RangerServiceException
POST
request to the Ranger Admin server to add data masking policy items to an existing policy identified by policyId
. The policyItems
parameter contains a list of data masking rules and associated principals. Upon successful completion, the updated RangerPolicy
object is returned. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
-
policyItems
— List of RangerDataMaskPolicyItem objects defining the data masking rules and principals to be added. policyId
— The ID of the policy to be updated.- Returns:
-
The updated
RangerPolicy
object -
Exceptions:
RangerServiceException
— If an error occurs during the API call
Update Data Mask Policy Items for an Existing Policy¶
public RangerPolicy updateDataMaskPolicyItems(long policyId, List<RangerPolicy.RangerDataMaskPolicyItem> policyItems) throws RangerServiceException
This method sends a PUT
request to the Ranger Admin server to update the data mask policy items for an existing policy identified by policyId
. The provided policyItems
replace the existing data mask entries for the specified principals in the policy if all conditions are met.
On successful update, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
-
policyId
— The ID of the policy to be updated. -
policyItems
— A list of RangerDataMaskPolicyItem objects defining the updated data mask rules and associated principals. -
Returns:
-
The updated
RangerPolicy
object reflecting the changes. -
Exceptions:
-
RangerServiceException
— If an error occurs during the API call.
Remove Principals from Data Mask Policy¶
public RangerPolicy deleteDataMaskPolicyItems(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap) throws RangerServiceException
DELETE
request to the Ranger Admin server to remove specified principals (users, groups, or roles) from the data mask policy identified by policyId
. The rangerPrincipalsMap
parameter provides the mapping of principal types to lists of principal names to be removed. On successful execution, the method returns the updated RangerPolicy
object reflecting the changes. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
-
policyId
— The ID of the policy from which principals should be removed. -
rangerPrincipalsMap
— A map of PrincipalType to lists of principal names (users, groups, or roles) to be removed. -
Returns:
-
The updated
RangerPolicy
object. -
Exceptions:
RangerServiceException
— If an error occurs during the API call.
Add Row Filter Policy Items to an Existing Policy¶
public RangerPolicy addRowFilterPolicyItems(long policyId, List<RangerPolicy.RangerRowFilterPolicyItem> policyItems) throws RangerServiceException
This method sends a POST
request to the Ranger Admin server to add one or more row filter policy items to an existing policy identified by policyId
. The policyItems
parameter contains the list of row filter rules and the associated principals to be added to the policy.
Upon successful execution, the method returns the updated RangerPolicy
object reflecting the new row filter items. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
-
policyId
— The ID of the policy to which the row filter items should be added. -
policyItems
— A list of RangerRowFilterPolicyItem objects defining the row filter rules and associated principals. -
Returns:
-
The updated
RangerPolicy
object with the new row filter items included. -
Exceptions:
-
RangerServiceException
— If an error occurs during the API call.
Update Row Filter Policy Items for an Existing Policy¶
public RangerPolicy updateRowFilterPolicyItems(long policyId, List<RangerPolicy.RangerRowFilterPolicyItem> policyItems) throws RangerServiceException
This method sends a PUT request to the Ranger Admin server to update the row filter policy items of an existing policy identified by policyId
. The policyItems
parameter contains the new row filter rules and associated principals to be applied.
If all conditions are met, the provided row filter policy items will replace the existing ones for the specified principals. On successful execution, the method returns the updated RangerPolicy
object. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
-
policyId
— The ID of the policy to be updated. -
policyItems
— A list of RangerRowFilterPolicyItem objects defining the updated row filter rules and associated principals. -
Returns:
-
The updated
RangerPolicy
object reflecting the changes. -
Exceptions:
RangerServiceException
— If an error occurs during the API call.
Remove Principals from a Row Filter Policy¶
public RangerPolicy deleteRowFilterPolicyItems(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap) throws RangerServiceException
This method sends a DELETE
request to the Ranger Admin server to remove specified principals (users, groups, or roles) from the row filter policy identified by policyId
. The rangerPrincipalsMap
parameter provides a mapping of principal types to lists of principal names that should be removed from the policy.
Upon successful execution, the method returns the updated RangerPolicy
object reflecting the changes. If an error occurs during the API call, a RangerServiceException
is thrown.
-
Parameters:
-
policyId
— The ID of the row filter policy from which principals should be removed. -
rangerPrincipalsMap
— A map where the key is a PrincipalType (e.g. USER, GROUP, ROLE) and the value is a list of principal names to be removed. -
Returns:
The updated RangerPolicy
object after removing the specified principals.
- Exceptions:
RangerServiceException
— If an error occurs during the API call.
Security Zone APIs¶
Create a new security zone in Apache Ranger.¶
public RangerSecurityZone createSecurityZone(RangerSecurityZone securityZone) throws RangerServiceException
This method sends a POST request to the Ranger Admin server to create a new security zone. The security zone details are provided in the securityZone
parameter. If the creation is successful, the method returns the created RangerSecurityZone
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
securityZone
— the security zone details to be created
- Returns:
- the created
RangerSecurityZone
object
- the created
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing security zone by ID.¶
public RangerSecurityZone updateSecurityZone(long zoneId, RangerSecurityZone securityZone) throws RangerServiceException
This method sends a PUT request to the Ranger Admin server to update an existing security zone. The security zone to be updated is identified by the zoneId
parameter, and the new security zone details are provided in the securityZone
parameter. If the update is successful, the method returns the updated RangerSecurityZone
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneId
— the ID of the security zone to be updatedsecurityZone
— the new security zone details
- Returns:
- the updated
RangerSecurityZone
object
- the updated
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a security zone by ID.¶
This method sends a DELETE request to the Ranger Admin server to delete an existing security zone. The security zone to be deleted is identified by the zoneId
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneId
— the ID of the security zone to be deleted
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a security zone by name.¶
This method sends a DELETE request to the Ranger Admin server to delete an existing security zone. The security zone to be deleted is identified by the zoneName
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneName
— the name of the security zone to be deleted
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a security zone by ID.¶
This method sends a GET request to the Ranger Admin server to retrieve an existing security zone. The security zone to be retrieved is identified by the zoneId
parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZone
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneId
— the ID of the security zone to be retrieved
- Returns:
- the retrieved
RangerSecurityZone
object
- the retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a security zone by name.¶
This method sends a GET request to the Ranger Admin server to retrieve an existing security zone. The security zone to be retrieved is identified by the zoneName
parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZone
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneName
— the name of the security zone to be retrieved
- Returns:
- the retrieved
RangerSecurityZone
object
- the retrieved
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve security zone headers based on filter criteria.¶
public List<RangerSecurityZoneHeaderInfo> getSecurityZoneHeaders(Map<String, String> filter) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to retrieve security zone headers that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter
parameter. If the retrieval is successful, the method returns a list of matching RangerSecurityZoneHeaderInfo
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
filter
— a map of key-value pairs representing the filter criteria
- Returns:
- a list of matching
RangerSecurityZoneHeaderInfo
objects
- a list of matching
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve security zone service headers based on filter criteria.¶
public List<RangerServiceHeaderInfo> getSecurityZoneServiceHeaders(Map<String, String> filter) throws RangerServiceException`
filter
parameter. If the retrieval is successful, the method returns a list of matching RangerServiceHeaderInfo
objects. If an error occurs during the API call, a RangerServiceException
is thrown. - Parameters:
filter
— a map of key-value pairs representing the filter criteria
- Returns:
- a list of matching
RangerServiceHeaderInfo
objects
- a list of matching
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve security zone names for a resource.¶
public Set<String> getSecurityZoneNamesForResource(String serviceName, Map<String, String> resource) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to retrieve security zone names for a resource. The service is identified by the serviceName
parameter, and the resource details are provided in the resource
parameter. If the retrieval is successful, the method returns a set of security zone names. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the serviceresource
— the resource details
- Returns:
- a set of security zone names
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Find security zones based on filter criteria.¶
public List<RangerSecurityZone> findSecurityZones(Map<String, String> filter) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to find security zones that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter
parameter. If the retrieval is successful, the method returns a list of matching RangerSecurityZone
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
filter
— a map of key-value pairs representing the filter criteria- Returns:
- a list of matching
RangerSecurityZone
objects - Exceptions:
RangerServiceException
— If an error occurs during the API call
Create a new security zone (version 2) in Apache Ranger.¶
public RangerSecurityZoneV2 createSecurityZoneV2(RangerSecurityZoneV2 securityZonev2) throws RangerServiceException`
This method sends a POST request to the Ranger Admin server to create a new security zone (version 2). The security zone details are provided in the securityZonev2
parameter. If the creation is successful, the method returns the created RangerSecurityZoneV2
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
securityZonev2
— the security zone details to be created- Returns:
- the created
RangerSecurityZoneV2
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing security zone (version 2) by ID.¶
public RangerSecurityZoneV2 updateSecurityZoneV2(long zoneId, RangerSecurityZoneV2 securityZoneV2) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to update an existing security zone. The security zone to be updated is identified by the zoneId
parameter, and the new security zone details are provided in the securityZoneV2
parameter. If the update is successful, the method returns the updated RangerSecurityZoneV2
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneId
— the ID of the security zone to be updatedsecurityZoneV2
— the new security zone details
- Returns:
- the updated
RangerSecurityZoneV2
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a security zone (version 2) by ID.¶
This method sends a GET request to the Ranger Admin server to retrieve an existing security zone (version 2). The security zone to be retrieved is identified by the zoneId
parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZoneV2
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneId
— the ID of the security zone to be retrieved- Returns:
- the retrieved
RangerSecurityZoneV2
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a security zone (version 2) by name.¶
This method sends a GET request to the Ranger Admin server to retrieve an existing security zone (version 2). The security zone to be retrieved is identified by the zoneName
parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZoneV2
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneName
— the name of the security zone to be retrieved- Returns:
- the retrieved
RangerSecurityZoneV2
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Partially update an existing security zone (version 2) by ID.¶
public Boolean updateSecurityZoneV2Partially(long zoneId, RangerSecurityZoneV2.RangerSecurityZoneChangeRequest rangerSecurityZoneChangeRequest) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to partially update an existing security zone (version 2). The security zone to be updated is identified by the zoneId
parameter, and the changes are provided in the rangerSecurityZoneChangeRequest
parameter. If the update is successful, the method returns a Boolean indicating the success of the operation. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
zoneId
— the ID of the security zone to be updatedrangerSecurityZoneChangeRequest
— the changes to be applied to the security zone
- Returns:
- a Boolean indicating the success of the operation
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a security zone (version 2) by ID.¶
This method sends a DELETE request to the Ranger Admin server to delete an existing security zone (version 2). The security zone to be deleted is identified by the id
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
id
— the ID of the security zone to be deleted- Exceptions:
RangerServiceException
— If an error occurs during the API call
Role APIs¶
Create a new role in Apache Ranger.¶
This method sends a POST request to the Ranger Admin server to create a new role. The role details are provided in the role
parameter. If the creation is successful, the method returns the created RangerRole
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicerole
— the role details to be created
- Returns:
- the created
RangerRole
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Update an existing role by ID.¶
This method sends a PUT request to the Ranger Admin server to update an existing role. The role to be updated is identified by the roleId
parameter, and the new role details are provided in the role
parameter. If the update is successful, the method returns the updated RangerRole
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
roleId
— the ID of the role to be updatedrole
— the new role details
- Returns:
- the updated
RangerRole
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a role by ID.¶
This method sends a DELETE request to the Ranger Admin server to delete an existing role. The role to be deleted is identified by the roleId
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
roleId
— the ID of the role to be deleted- Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete a role by name.¶
public void deleteRole(String roleName, String execUser, String serviceName) throws RangerServiceException`
This method sends a DELETE request to the Ranger Admin server to delete an existing role. The role to be deleted is identified by the roleName
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
roleName
— the name of the role to be deletedexecUser
— the user executing the requestserviceName
— the name of the service
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a role by ID.¶
This method sends a GET request to the Ranger Admin server to retrieve an existing role. The role to be retrieved is identified by the roleId
parameter. If the retrieval is successful, the method returns the retrieved RangerRole
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
roleId
— the ID of the role to be retrieved- Returns:
- the retrieved
RangerRole
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve a role by name.¶
public RangerRole getRole(String roleName, String execUser, String serviceName) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to retrieve an existing role. The role to be retrieved is identified by the roleName
parameter. If the retrieval is successful, the method returns the retrieved RangerRole
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
roleName
— the name of the role to be retrievedexecUser
— the user executing the requestserviceName
— the name of the service
- Returns:
- The retrieved
RangerRole
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve all role names for a service.¶
public List<String> getAllRoleNames(String execUser, String serviceName) throws RangerServiceException`
This method sends a GET request to the Ranger Admin server to retrieve all role names for a service. The service is identified by the serviceName
parameter. If the retrieval is successful, the method returns a list of role names. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
execUser
— the user executing the requestserviceName
— the name of the service
- Returns:
- a list of role names
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve roles for a user.¶
This method sends a GET request to the Ranger Admin server to retrieve roles for a user. The user is identified by the user
parameter. If the retrieval is successful, the method returns a list of roles. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
user
— the user whose roles are to be retrieved- Returns:
- a list of roles
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Find roles based on filter criteria.¶
This method sends a GET request to the Ranger Admin server to find roles that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter
parameter. If the retrieval is successful, the method returns a list of matching RangerRole
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
filter
— a map of key-value pairs representing the filter criteria- Returns:
- a list of matching
RangerRole
objects - Exceptions:
RangerServiceException
— If an error occurs during the API call
Grant a role to a user or group.¶
public RESTResponse grantRole(String serviceName, GrantRevokeRoleRequest request) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to grant a role to a user or group. The role details are provided in the request
parameter. If the grant is successful, the method returns a RESTResponse
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicerequest
— the role grant request details
- Returns:
- a
RESTResponse
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Revoke a role from a user or group.¶
public RESTResponse revokeRole(String serviceName, GrantRevokeRoleRequest request) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to revoke a role from a user or group. The role details are provided in the request
parameter. If the revoke is successful, the method returns a RESTResponse
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicerequest
— the role revoke request details
- Returns:
- a
RESTResponse
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Import service tags into Apache Ranger.¶
public void importServiceTags(String serviceName, RangerServiceTags svcTags) throws RangerServiceException`
This method sends a PUT request to the Ranger Admin server to import service tags. The service is identified by the serviceName
parameter, and the tags to be imported are provided in the svcTags
parameter. If the import is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the servicesvcTags
— the service tags to be imported
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve service tags from Apache Ranger.¶
This method sends a GET request to the Ranger Admin server to retrieve service tags. The service is identified by the serviceName
parameter. If the retrieval is successful, the method returns the retrieved RangerServiceTags
object. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
serviceName
— the name of the service- Returns:
- The retrieved
RangerServiceTags
object - Exceptions:
RangerServiceException
— If an error occurs during the API call
Retrieve plugin information from Apache Ranger.¶
This method sends a GET request to the Ranger Admin server to retrieve plugin information. If the retrieval is successful, the method returns a list of RangerPluginInfo
objects. If an error occurs during the API call, a RangerServiceException
is thrown.
- Returns:
- a list of
RangerPluginInfo
objects - Exceptions:
RangerServiceException
— If an error occurs during the API call
Delete policy deltas from Apache Ranger.¶
public void deletePolicyDeltas(int days, boolean reloadServicePoliciesCache) throws RangerServiceException`
This method sends a DELETE request to the Ranger Admin server to delete policy deltas. The number of days to retain is specified by the days
parameter, and whether to reload the service policies cache is specified by the reloadServicePoliciesCache
parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
days
— the number of days to retainreloadServicePoliciesCache
— whether to reload the service policies cache
- Exceptions:
RangerServiceException
— If an error occurs during the API call
Purge records from Apache Ranger.¶
public List<RangerPurgeResult> purgeRecords(String recordType, int retentionDays) throws RangerServiceException`
This method sends a DELETE request to the Ranger Admin server to purge records. The type of records to purge is specified by the recordType
parameter, and the retention period is specified by the retentionDays
parameter. The recordType parameter can be one of the following: login_records, trx_records, policy_export_logs If the purge is successful, the method returns a list of RangerPurgeResult
objects. T If an error occurs during the API call, a RangerServiceException
is thrown.
- Parameters:
recordType
— the type of records to purgeretentionDays
— the retention period in days
- Returns: a list of
RangerPurgeResult
objects- Exceptions:
RangerServiceException
— If an error occurs during the API call