Quản lý lời mời cấp quyền truy cập cho người dùng

Là quản trị viên Google Ads, bạn có thể quản lý lời mời cấp quyền truy cập của người dùng vào tài khoản Google Ads. Để gọi các API này, người dùng được xác thực phải có đặc quyền truy cập ADMIN trên tài khoản khách hàng mục tiêu.

Mời người dùng

Lưu ý: Khi tạo lời mời, bạn phải chỉ định một địa chỉ email hợp lệ và chỉ định access_role phù hợp. Google Ads API có thể tạo yêu cầu phê duyệt nhiều bên để hoàn tất hành động này. Hãy tham khảo hướng dẫn phê duyệt nhiều bên để tìm hiểu thêm.

Bạn có thể gửi lời mời qua email cho người dùng mới trong quá trình quản lý quyền truy cập vào tài khoản Google Ads. Bạn có thể thực hiện việc này bằng cách tạo mới CustomerUserAccessInvitation bằng phương thức MutateCustomerUserAccessInvitation của CustomerUserAccessInvitationService.

Người dùng nhận được lời mời phải chấp nhận lời mời qua email theo cách thủ công. Người dùng cũng có thể chấp nhận lời mời bằng một địa chỉ email thay thế. Có thể mất tối đa 24 giờ để trạng thái thay đổi từ đang chờ xử lý sau khi lời mời được chấp nhận. Sau khi xác nhận, bạn có thể quản lý vai trò và quyền truy cập của người dùng như mô tả trong Quản lý quyền truy cập của người dùng.

Nếu Google xác định rằng cần có quy trình phê duyệt nhiều bên:

• MutateCustomerUserAccessInvitationResult sẽ điền vào trường multi_party_auth_review chứa tên tài nguyên của yêu cầu xem xét đang chờ xử lý cần được phê duyệt.
• Trường resource_name sẽ không được điền.
• Bạn không thể gửi lời mời mới cho cùng một địa chỉ email cho đến khi yêu cầu phê duyệt nhiều bên đang chờ xử lý được giải quyết.
• Quản trị viên thứ hai có thể phê duyệt hoặc từ chối yêu cầu xem xét đang chờ xử lý bằng phương thức ResolveMultiPartyAuthReview. Hãy tham khảo hướng dẫn phê duyệt nhiều bên để tìm hiểu thêm.

Đoạn mã này cho biết cách gửi lời mời:

Java

// Constructs an access invitation.
CustomerUserAccessInvitation invitation =
    CustomerUserAccessInvitation.newBuilder()
        .setEmailAddress(emailAddress)
        .setAccessRole(accessRole)
        .build();

// Constructs an operation to send the invitation.
CustomerUserAccessInvitationOperation operation =
    CustomerUserAccessInvitationOperation.newBuilder().setCreate(invitation).build();

// Creates a CustomerUserAccessInvitationServiceClient.
try (CustomerUserAccessInvitationServiceClient client =
    googleAdsClient.getLatestVersion().createCustomerUserAccessInvitationServiceClient()) {
  // Issues the request.
  MutateCustomerUserAccessInvitationResponse response =
      client.mutateCustomerUserAccessInvitation(String.valueOf(customerId), operation);

  if (response.getResult().getMultiPartyAuthReview().isEmpty()) {
    // A multi-party auth review was not triggered.
    System.out.printf(
        "Customer user access invitation was sent for customerId = "
            + "%d to email address = '%s' and access role = '%s'. The invitation resource "
            + "name is '%s'.%n",
        customerId, emailAddress, accessRole, response.getResult().getResourceName());
  } else {
    // A multi-party auth review was triggered. See
    // FetchAndApprovePendingMultiPartyAuthReviews.java for an example on how to fetch
    // and approve an MPA auth review.
    System.out.printf(
        "A multi-party auth review was triggered. The MPA review resource name is %s. "
            + "Ask a second administrator to approve this request to send user access invitation. "
            + "See FetchAndApprovePendingMultiPartyAuthReviews.java for an example on "
            + "how to approve an MPA auth review using the API.%n",
        response.getResult().getMultiPartyAuthReview());
  }
}
InviteUserWithAccessRole.java
      

C#

MutateCustomerUserAccessInvitationRequest invitationRequest =
    new MutateCustomerUserAccessInvitationRequest()
    {
        CustomerId = customerId.ToString(),
        Operation = new CustomerUserAccessInvitationOperation()
        {
            Create = new CustomerUserAccessInvitation()
            {
                EmailAddress = emailAddress,
                AccessRole = accessRole
            },
        }
    };
try
{
    var response = service.MutateCustomerUserAccessInvitation(invitationRequest);

    if (response.Result.MultiPartyAuthReview == null)
    {
        // A multi-party auth review was not triggered.
        Console.WriteLine("Customer user access invitation was sent for " +
            $"customerId = {customerId} to email address = {emailAddress} and " +
            $"access role = {accessRole}. The invitation resource name is " +
            $"{response.Result.ResourceName}.");
    }
    else 
    {
        // A multi-party auth review was triggered. See
        // FetchAndApprovePendingMultiPartyAuthReviews.cs for an example on how to fetch
        // and approve an MPA auth review.
        Console.WriteLine($"A multi-party auth review was triggered. The MPA review " +
            $"resource name is {response.Result.MultiPartyAuthReview}. Ask a second " +
            $"administrator to approve this request to send user access invitation. " +
            $"See FetchAndApprovePendingMultiPartyAuthReviews.cs for an example on " +
            $"how to approve an MPA auth review using the API.");
    }
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");
    Console.WriteLine($"Failure: {e.Failure}");
    Console.WriteLine($"Request ID: {e.RequestId}");
    throw;
}
InviteUserWithAccessRole.cs
      

PHP

// Creates a customer user access invitation.
$customerUserAccessInvitation = new CustomerUserAccessInvitation([
    'email_address' =>  $emailAddress,
    'access_role' => AccessRole::value($accessRole)
]);

// Creates a customer user access invitation operation.
$customerUserAccessInvitationOperation = new CustomerUserAccessInvitationOperation();
$customerUserAccessInvitationOperation->setCreate($customerUserAccessInvitation);

// Issues a mutate request to send the customer user access invitation and prints its
// information.
$customerUserAccessInvitationServiceClient =
    $googleAdsClient->getCustomerUserAccessInvitationServiceClient();
$response = $customerUserAccessInvitationServiceClient->mutateCustomerUserAccessInvitation(
    MutateCustomerUserAccessInvitationRequest::build(
        $customerId,
        $customerUserAccessInvitationOperation
    )
);
printf(
    "Customer user access invitation with resource name '%s' was sent from customer "
    . "ID %d to email address '%s' with access role '%s'.%s",
    $response->getResult()->getResourceName(),
    $customerId,
    $emailAddress,
    $accessRole,
    PHP_EOL
);
InviteUserWithAccessRole.php
      

Python

invitation_operation: CustomerUserAccessInvitationOperation = (
    client.get_type("CustomerUserAccessInvitationOperation")
)
invitation: CustomerUserAccessInvitation = invitation_operation.create
invitation.email_address = email_address
# The access_role field in the CustomerUserAccessInvitation message expects
# an AccessRoleEnum value (which is an int).
invitation.access_role = client.enums.AccessRoleEnum[access_role].value

response: MutateCustomerUserAccessInvitationResponse = (
    service.mutate_customer_user_access_invitation(
        customer_id=customer_id, operation=invitation_operation
    )
)
if response.result.multi_party_auth_review:
    # A multi-party auth review was triggered. See
    # FetchAndApprovePendingMultiPartyAuthReviews.cs for an example on how
    # to fetch and approve an MPA auth review.
    print(
        "A multi-party auth review was triggered. The MPA review resource "
        f"name is {response.result.multi_party_auth_review}. Ask a second "
        "administrator to approve this request to send user access invitation. "
        "See advanced_operations/fetch_and_approve_pending_multi_party_auth_reviews.py "
        "for an example on how to approve an MPA auth review using the API."
    )
else:
    # A multi-party auth review was not triggered.
    print(
        "Customer user access invitation was sent for "
        f"customer ID: '{customer_id}', "
        f"email address {email_address}, and "
        f"access role {access_role}. The invitation resource name is: "
        f"{response.result.resource_name}"
    )
invite_user_with_access_role.py
      

Ruby

operation = client.operation.create_resource.customer_user_access_invitation do |inv|
  inv.email_address = email_address
  inv.access_role = access_role
end

# Issues a mutate request to get the response.
response = client.service.customer_user_access_invitation.mutate_customer_user_access_invitation(
  customer_id: customer_id,
  operation: operation,
)

# Prints out information of the created invitation.
puts "Customer user access invitation was sent for customerId = #{customer_id} " \
  "email address = '#{email_address}', " \
  "access role = '#{access_role}'."
invite_user_with_access_role.rb
      

Perl

sub invite_user_with_access_role {
  my ($api_client, $customer_id, $email_address, $access_role) = @_;

  # Create the user access invitation.
  my $user_access_invitation =
    Google::Ads::GoogleAds::V25::Resources::CustomerUserAccessInvitation->new({
      emailAddress => $email_address,
      accessRole   => $access_role
    });

  # Create the user access invitation operation.
  my $invitation_operation =
    Google::Ads::GoogleAds::V25::Services::CustomerUserAccessInvitationService::CustomerUserAccessInvitationOperation
    ->new({create => $user_access_invitation});

  # Send the user access invitation.
  my $invitation_response =
    $api_client->CustomerUserAccessInvitationService()->mutate({
      customerId => $customer_id,
      operation  => $invitation_operation
    });

  if (not $invitation_response->{result}{multiPartyAuthReview}) {
    printf "Customer user access invitation was sent for customerId = %d " .
      "to email address = '%s' and access role = '%s'. " .
      "The invitation resource name is '%s'.\n",
      $customer_id, $email_address, $access_role,
      $invitation_response->{result}{resourceName};
  } else {
    printf "A multi-party auth review was triggered. The MPA review " .
      "resource name is '%s'. Ask a second administrator to approve this " .
      "request to send user access invitation. See " .
      "fetch_and_approve_pending_multi_party_auth_reviews.pl for an example " .
      "on how to approve an MPA auth review using the API.\n",
      $invitation_response->{result}{multiPartyAuthReview};
  }

  return 1;
}
invite_user_with_access_role.pl
      

curl

# This code example sends an invitation email to a user.
#
# The invitation is to manage a customer account with a desired access role.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
#   EMAIL_ADDRESS: The email address of the user to invite.
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/customerUserAccessInvitations:mutate" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "operation": {
    "create": {
      "emailAddress": "${EMAIL_ADDRESS}",
      "accessRole": "ADMIN"
    }
  }
}
EOF
invite_user_with_access_role.sh
      

Thu hồi lời mời

Bạn có thể thu hồi lời mời đang chờ xử lý bằng cách thực thi thao tác remove bằng phương thức MutateCustomerUserAccessInvitation CustomerUserAccessInvitationService, chuyển tên tài nguyên của lời mời cần xoá.

Truy xuất lời mời người dùng

Bạn có thể truy xuất danh sách lời mời người dùng đang chờ xử lý bằng cách tạo câu lệnh Ngôn ngữ truy vấn Google Ads để truy vấn tất cả thực thể CustomerUserAccessInvitation được liên kết với mã khách hàng. Sau đây là một truy vấn thông thường:

SELECT
  customer_user_access_invitation.invitation_id,
  customer_user_access_invitation.email_address,
  customer_user_access_invitation.access_role,
  customer_user_access_invitation.invitation_status,
  customer_user_access_invitation.creation_date_time
FROM customer_user_access_invitation

Lưu ý: Nếu lời mời người dùng đang chờ quy trình phê duyệt nhiều bên, thì lời mời đó sẽ không xuất hiện khi bạn truy xuất lời mời người dùng bằng phương thức GoogleAdsService.Search hoặc GoogleAdsService.SearchStream method.

Bạn có thể thêm các điều kiện lọc bổ sung để truy xuất tập hợp con của lời mời. Ví dụ: trường hợp sử dụng phổ biến là truy xuất danh sách lời mời người dùng đang chờ xử lý bằng cách lọc theo customer_user_access_invitation.invitation_status = PENDING.