UpdateUserRoles Service Operation - Customer Management

Artikkeli
11/13/2024

Updates the roles of the specified user.

Note

Only a user with Super Admin or Standard credentials can update user roles. A Standard user cannot set or modify the Super Admin role. For more information, see the User Roles technical guide.

For users with an account role, you can add and delete the accounts that the user has access to. For users with a customer role, you can add and delete the customers that the user has access to. You can also change a user from having an account role to having a customer role or vice-versa.

Request Elements

The UpdateUserRolesRequest object defines the body and header elements of the service operation request. The elements must be in the same order as shown in the Request SOAP.

Note

Unless otherwise noted below, all request elements are required.

Request Body Elements

Element	Description	Data Type
CustomerId	The identifier of the customer to which the user belongs.	long
DeleteAccountIds	An array of identifiers of the accounts to remove from the list of accounts that the user can manage. For usage, see the Remarks section below.	long array
DeleteCustomerIds	An array of identifiers of the customers to remove from the list of customers that the user can manage. For usage, see the Remarks section below.	long array
DeleteRoleId	The identifier of the role to which the values specified in the DeleteAccountIds or DeleteCustomerIds element applies, if set. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.	int
NewAccountIds	An array of identifiers of the accounts to restrict the user to. The user will be able to manage only these accounts. If the user is currently restricted to a set of accounts, set this element to the new accounts that you want the user to also manage. For example, if the user currently manages accounts 123 and 456, and you want the user to also manage account 789, set this element to 789. For usage, see the Remarks section below.	long array
NewCustomerIds	An array of identifiers of the customers to restrict the user to. The user will be able to manage only these customers. For usage, see the Remarks section below.	long array
NewRoleId	The identifier of the role to which the values specified in the NewAccountIds or NewCustomerIds element applies to, if set. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.	int
UserId	The identifier of the user whose role you want to update.	long

Request Header Elements

Element	Description	Data Type
AuthenticationToken	The OAuth access token that represents the credentials of a user who has permissions to Microsoft Advertising accounts. For more information see Authentication with OAuth.	string
DeveloperToken	The developer token used to access the Bing Ads API. For more information see Get a Developer Token.	string
Password	This element is reserved for internal use and will be removed from a future version of the API. You must use the AuthenticationToken element to set user credentials.	string
UserName	This element is reserved for internal use and will be removed from a future version of the API. You must use the AuthenticationToken element to set user credentials.	string

Response Elements

The UpdateUserRolesResponse object defines the body and header elements of the service operation response. The elements are returned in the same order as shown in the Response SOAP.

Response Body Elements

Element	Description	Data Type
LastModifiedTime	The date and time that the user roles were last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.	dateTime

Response Header Elements

Element	Description	Data Type
TrackingId	The identifier of the log entry that contains the details of the API call.	string

Request SOAP

This template was generated by a tool to show the order of the body and header elements for the SOAP request. For supported types that you can use with this service operation, see the Request Body Elements reference above.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/Customer/v13">
    <Action mustUnderstand="1">UpdateUserRoles</Action>
    <AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
    <DeveloperToken i:nil="false">ValueHere</DeveloperToken>
  </s:Header>
  <s:Body>
    <UpdateUserRolesRequest xmlns="https://bingads.microsoft.com/Customer/v13">
      <CustomerId>ValueHere</CustomerId>
      <UserId>ValueHere</UserId>
      <NewRoleId i:nil="false">ValueHere</NewRoleId>
      <NewAccountIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </NewAccountIds>
      <NewCustomerIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </NewCustomerIds>
      <DeleteRoleId i:nil="false">ValueHere</DeleteRoleId>
      <DeleteAccountIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </DeleteAccountIds>
      <DeleteCustomerIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </DeleteCustomerIds>
    </UpdateUserRolesRequest>
  </s:Body>
</s:Envelope>

Response SOAP

This template was generated by a tool to show the order of the body and header elements for the SOAP response.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/Customer/v13">
    <TrackingId d3p1:nil="false" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance">ValueHere</TrackingId>
  </s:Header>
  <s:Body>
    <UpdateUserRolesResponse xmlns="https://bingads.microsoft.com/Customer/v13">
      <LastModifiedTime>ValueHere</LastModifiedTime>
    </UpdateUserRolesResponse>
  </s:Body>
</s:Envelope>

Code Syntax

The example syntax can be used with Bing Ads SDKs. See Bing Ads API Code Examples for more examples.

public async Task<UpdateUserRolesResponse> UpdateUserRolesAsync(
	long customerId,
	long userId,
	int? newRoleId,
	IList<long> newAccountIds,
	IList<long> newCustomerIds,
	int? deleteRoleId,
	IList<long> deleteAccountIds,
	IList<long> deleteCustomerIds)
{
	var request = new UpdateUserRolesRequest
	{
		CustomerId = customerId,
		UserId = userId,
		NewRoleId = newRoleId,
		NewAccountIds = newAccountIds,
		NewCustomerIds = newCustomerIds,
		DeleteRoleId = deleteRoleId,
		DeleteAccountIds = deleteAccountIds,
		DeleteCustomerIds = deleteCustomerIds
	};

	return (await CustomerManagementService.CallAsync((s, r) => s.UpdateUserRolesAsync(r), request));
}

static UpdateUserRolesResponse updateUserRoles(
	java.lang.Long customerId,
	java.lang.Long userId,
	int newRoleId,
	ArrayOflong newAccountIds,
	ArrayOflong newCustomerIds,
	int deleteRoleId,
	ArrayOflong deleteAccountIds,
	ArrayOflong deleteCustomerIds) throws RemoteException, Exception
{
	UpdateUserRolesRequest request = new UpdateUserRolesRequest();

	request.setCustomerId(customerId);
	request.setUserId(userId);
	request.setNewRoleId(newRoleId);
	request.setNewAccountIds(newAccountIds);
	request.setNewCustomerIds(newCustomerIds);
	request.setDeleteRoleId(deleteRoleId);
	request.setDeleteAccountIds(deleteAccountIds);
	request.setDeleteCustomerIds(deleteCustomerIds);

	return CustomerManagementService.getService().updateUserRoles(request);
}

static function UpdateUserRoles(
	$customerId,
	$userId,
	$newRoleId,
	$newAccountIds,
	$newCustomerIds,
	$deleteRoleId,
	$deleteAccountIds,
	$deleteCustomerIds)
{

	$GLOBALS['Proxy'] = $GLOBALS['CustomerManagementProxy'];

	$request = new UpdateUserRolesRequest();

	$request->CustomerId = $customerId;
	$request->UserId = $userId;
	$request->NewRoleId = $newRoleId;
	$request->NewAccountIds = $newAccountIds;
	$request->NewCustomerIds = $newCustomerIds;
	$request->DeleteRoleId = $deleteRoleId;
	$request->DeleteAccountIds = $deleteAccountIds;
	$request->DeleteCustomerIds = $deleteCustomerIds;

	return $GLOBALS['CustomerManagementProxy']->GetService()->UpdateUserRoles($request);
}

response=customermanagement_service.UpdateUserRoles(
	CustomerId=CustomerId,
	UserId=UserId,
	NewRoleId=NewRoleId,
	NewAccountIds=NewAccountIds,
	NewCustomerIds=NewCustomerIds,
	DeleteRoleId=DeleteRoleId,
	DeleteAccountIds=DeleteAccountIds,
	DeleteCustomerIds=DeleteCustomerIds)

Remarks

As an example use case if an advertiser campaign manager is limited to managing accounts 123, 456, and 789, and you no longer want the user to manage 456, set the following elements accordingly:

Set the NewRoleId element to 16 (advertiser campaign manager role).
Set the NewAccountIds element to an array that contains 123 and 789.
Set the DeleteRoleId element to 16 (advertiser campaign manager role).
Set the DeleteAccountIds element to an array that contains 456.

If an advertiser campaign manager is limited to managing accounts 123 and 789, and you now want the user to manage all accounts, set the following elements accordingly:

Set the NewRoleId element to 16 (advertiser campaign manager role).
Set the NewAccountIds element to NULL.
Set the DeleteRoleId element to 16 (advertiser campaign manager role).
Set the DeleteAccountIds element to an array that contains 123, 456, and 789.

Users with account level roles can be restricted to specific accounts. Users with customer level roles can access all accounts within the user's customer, and their access cannot be restricted to specific accounts.

Note

When attempting to restrict customer level user roles to specific accounts the UpdateUserRoles operation will not fail, and the user will retain access for all accounts within the user's customer.

Requirements

Service: CustomerManagementService.svc v13
Namespace: https://bingads.microsoft.com/Customer/v13

https://clientcenter.api.bingads.microsoft.com/CustomerManagement/v13/UserRoles

https://clientcenter.api.sandbox.bingads.microsoft.com/CustomerManagement/v13/UserRoles

Request Elements

The UpdateUserRolesRequest object defines the body and header elements of the service operation request.

Note

Unless otherwise noted below, all request elements are required.

Request Body Elements

Element	Description	Data Type
CustomerId	The identifier of the customer to which the user belongs.	long
DeleteAccountIds	An array of identifiers of the accounts to remove from the list of accounts that the user can manage. For usage, see the Remarks section below.	long array
DeleteCustomerIds	An array of identifiers of the customers to remove from the list of customers that the user can manage. For usage, see the Remarks section below.	long array
DeleteRoleId	The identifier of the role to which the values specified in the DeleteAccountIds or DeleteCustomerIds element applies, if set. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.	int
NewAccountIds	An array of identifiers of the accounts to restrict the user to. The user will be able to manage only these accounts. If the user is currently restricted to a set of accounts, set this element to the new accounts that you want the user to also manage. For example, if the user currently manages accounts 123 and 456, and you want the user to also manage account 789, set this element to 789. For usage, see the Remarks section below.	long array
NewCustomerIds	An array of identifiers of the customers to restrict the user to. The user will be able to manage only these customers. For usage, see the Remarks section below.	long array
NewRoleId	The identifier of the role to which the values specified in the NewAccountIds or NewCustomerIds element applies to, if set. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.	int
UserId	The identifier of the user whose role you want to update.	long

Request Header Elements

Element	Description	Data Type
Authorization	The OAuth access token that represents the credentials of a user who has permissions to Microsoft Advertising accounts. Please ensure that the token is prefixed with "Bearer ", this is necessary for proper authentication. For more information see Authentication with OAuth.	string
DeveloperToken	The developer token used to access the Bing Ads API. For more information see Get a Developer Token.	string
Password	This element is reserved for internal use and will be removed from a future version of the API. You must use the AuthenticationToken element to set user credentials.	string
UserName	This element is reserved for internal use and will be removed from a future version of the API. You must use the AuthenticationToken element to set user credentials.	string

Response Elements

The UpdateUserRolesResponse object defines the body and header elements of the service operation response. The elements are returned in the same order as shown in the Response JSON.

Response Body Elements

Element	Description	Data Type
LastModifiedTime	The date and time that the user roles were last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.	dateTime

Response Header Elements

Element	Description	Data Type
TrackingId	The identifier of the log entry that contains the details of the API call.	string

Request JSON

This template was generated by a tool to show the body and header elements for the JSON request. For supported types that you can use with this service operation, see the Request Body Elements reference above.

{
  "CustomerId": "LongValueHere",
  "UserId": "LongValueHere",
  "NewRoleId": IntValueHere,
  "NewAccountIds": [
    "LongValueHere"
  ],
  "NewCustomerIds": [
    "LongValueHere"
  ],
  "DeleteRoleId": IntValueHere,
  "DeleteAccountIds": [
    "LongValueHere"
  ],
  "DeleteCustomerIds": [
    "LongValueHere"
  ]
}

Response JSON

This template was generated by a tool to show the body and header elements for the JSON response.

{
  "LastModifiedTime": "ValueHere"
}

Code Syntax

To call REST API through SDKs, you need to upgrade SDK to a certain version and configure the system parameters.The example syntax can be used with Bing Ads SDKs. See Bing Ads API Code Examples for more examples.

public async Task<UpdateUserRolesResponse> UpdateUserRolesAsync(
	long customerId,
	long userId,
	int? newRoleId,
	IList<long> newAccountIds,
	IList<long> newCustomerIds,
	int? deleteRoleId,
	IList<long> deleteAccountIds,
	IList<long> deleteCustomerIds)
{
	var request = new UpdateUserRolesRequest
	{
		CustomerId = customerId,
		UserId = userId,
		NewRoleId = newRoleId,
		NewAccountIds = newAccountIds,
		NewCustomerIds = newCustomerIds,
		DeleteRoleId = deleteRoleId,
		DeleteAccountIds = deleteAccountIds,
		DeleteCustomerIds = deleteCustomerIds
	};

	return (await CustomerManagementService.CallAsync((s, r) => s.UpdateUserRolesAsync(r), request));
}

static UpdateUserRolesResponse updateUserRoles(
	java.lang.Long customerId,
	java.lang.Long userId,
	int newRoleId,
	ArrayOflong newAccountIds,
	ArrayOflong newCustomerIds,
	int deleteRoleId,
	ArrayOflong deleteAccountIds,
	ArrayOflong deleteCustomerIds) throws RemoteException, Exception
{
	UpdateUserRolesRequest request = new UpdateUserRolesRequest();

	request.setCustomerId(customerId);
	request.setUserId(userId);
	request.setNewRoleId(newRoleId);
	request.setNewAccountIds(newAccountIds);
	request.setNewCustomerIds(newCustomerIds);
	request.setDeleteRoleId(deleteRoleId);
	request.setDeleteAccountIds(deleteAccountIds);
	request.setDeleteCustomerIds(deleteCustomerIds);

	return CustomerManagementService.getService().updateUserRoles(request);
}

static function UpdateUserRoles(
	$customerId,
	$userId,
	$newRoleId,
	$newAccountIds,
	$newCustomerIds,
	$deleteRoleId,
	$deleteAccountIds,
	$deleteCustomerIds)
{

	$GLOBALS['Proxy'] = $GLOBALS['CustomerManagementProxy'];

	$request = new UpdateUserRolesRequest();

	$request->CustomerId = $customerId;
	$request->UserId = $userId;
	$request->NewRoleId = $newRoleId;
	$request->NewAccountIds = $newAccountIds;
	$request->NewCustomerIds = $newCustomerIds;
	$request->DeleteRoleId = $deleteRoleId;
	$request->DeleteAccountIds = $deleteAccountIds;
	$request->DeleteCustomerIds = $deleteCustomerIds;

	return $GLOBALS['CustomerManagementProxy']->GetService()->UpdateUserRoles($request);
}

response=customermanagement_service.UpdateUserRoles(
	CustomerId=CustomerId,
	UserId=UserId,
	NewRoleId=NewRoleId,
	NewAccountIds=NewAccountIds,
	NewCustomerIds=NewCustomerIds,
	DeleteRoleId=DeleteRoleId,
	DeleteAccountIds=DeleteAccountIds,
	DeleteCustomerIds=DeleteCustomerIds)

Remarks

As an example use case if an advertiser campaign manager is limited to managing accounts 123, 456, and 789, and you no longer want the user to manage 456, set the following elements accordingly:

Set the NewRoleId element to 16 (advertiser campaign manager role).
Set the NewAccountIds element to an array that contains 123 and 789.
Set the DeleteRoleId element to 16 (advertiser campaign manager role).
Set the DeleteAccountIds element to an array that contains 456.

If an advertiser campaign manager is limited to managing accounts 123 and 789, and you now want the user to manage all accounts, set the following elements accordingly:

Set the NewRoleId element to 16 (advertiser campaign manager role).
Set the NewAccountIds element to NULL.
Set the DeleteRoleId element to 16 (advertiser campaign manager role).
Set the DeleteAccountIds element to an array that contains 123, 456, and 789.

Note

When attempting to restrict customer level user roles to specific accounts the UpdateUserRoles operation will not fail, and the user will retain access for all accounts within the user's customer.

Jaa

UpdateUserRoles Service Operation - Customer Management

Request Elements

Request Body Elements

Request Header Elements

Response Elements

Response Body Elements

Response Header Elements

Request SOAP

Response SOAP

Code Syntax

Remarks

Requirements

Request Url

Request Elements

Request Body Elements

Request Header Elements

Response Elements

Response Body Elements

Response Header Elements

Request JSON

Response JSON

Code Syntax

Remarks

Palaute

Lisäresursseja