مدیریت دعوت‌های دسترسی کاربر

به‌عنوان سرپرست Google Ads، می‌توانید دعوت‌های دسترسی کاربر به حساب Google Ads را مدیریت کنید. فراخوانی این میاناهای برنامه‌سازی کاربردی به کاربر اصالت‌سنجی‌شده با امتیازات دسترسی ADMIN در حساب مشتری هدف نیاز دارد.

دعوت از کاربران

توجه: هنگام ایجاد دعوت، باید نشانی ایمیل معتبری را مشخص کنید و access_role مناسبی را اختصاص دهید. Google Ads API ممکن است برای تکمیل این کنش، درخواست تأیید چندنفره ایجاد کند. برای کسب اطلاعات بیشتر، به راهنمای تأیید چندطرفه مراجعه کنید.

می‌توانید به‌عنوان بخشی از مدیریت دسترسی به حساب Google Ads، دعوت‌نامه ایمیلی برای کاربر جدید ارسال کنید. این کار با ایجاد CustomerUserAccessInvitation جدید بااستفاده از روش MutateCustomerUserAccessInvitation CustomerUserAccessInvitationService انجام می‌شود.

کاربری که دعوت را دریافت کرده است باید دعوت ایمیلی را به‌صورت دستی بپذیرد. کاربر همچنین می‌تواند دعوت را بااستفاده از نشانی ایمیل جایگزین بپذیرد. پس‌از پذیرفته شدن دعوت، ممکن است تا ۲۴ ساعت طول بکشد تا وضعیت از «درحال انتظار» تغییر کند. پس‌از تأیید، می‌توانید نقش و دسترسی کاربر را همان‌طور که در مدیریت دسترسی کاربر شرح داده شده است مدیریت کنید.

اگر Google تشخیص دهد که تأیید چندجانبه لازم است:

• MutateCustomerUserAccessInvitationResult فیلد multi_party_auth_review را که حاوی نام منبع مرور معلقه نیازمند تأیید است پر می‌کند.
• فیلد resource_name تکمیل نخواهد شد.
• تا زمانی که درخواست تأیید چندجانبه معلقه حل‌وفصل نشود، نمی‌توان دعوت جدیدی برای همان نشانی ایمیل ارسال کرد.
• درخواست بازبینی معلقه را می‌توان توسط سرپرست دوم بااستفاده از روش ResolveMultiPartyAuthReview تأیید یا رد کرد. برای کسب اطلاعات بیشتر، به راهنمای تأیید چندطرفه مراجعه کنید.

این تکه‌کد نحوه ارسال دعوت را نشان می‌دهد:

جاوا

// 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
      

پرل

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
      

فر کردن

# 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
      

لغو کردن دعوت‌ها

می‌توانید دعوت معلقه را با اجرای عملیات remove با روش MutateCustomerUserAccessInvitation از CustomerUserAccessInvitationService و ارسال نام منبع دعوت برای برداشتن لغو کنید.

بازیابی دعوت‌های کاربر

با ساختن عبارت زبان پُرسمان Google Ads می‌توانید فهرست دعوت‌های کاربر معلقه را بازیابی کنید تا همه نهادهای CustomerUserAccessInvitation مرتبط با شناسه مشتری را پُرسمان کنید. در اینجا یک پُرسمان معمول آورده شده است:

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

توجه: اگر دعوت کاربر درانتظار تأیید چندطرفه باشد، هنگام بازیابی دعوت‌های کاربر بااستفاده از روش GoogleAdsService.Search یا GoogleAdsService.SearchStream نشان داده نخواهد شد.

می‌توانید شرایط فیلتر کردن بیشتری اضافه کنید تا زیرمجموعه‌های دعوت‌ها را بازیابی کنید. برای مثال، یک مورد استفاده رایج، بازیابی فهرست دعوت‌های معلق کاربر با فیلتر کردن برای customer_user_access_invitation.invitation_status = PENDING است.