إدارة دعوات وصول المستخدمين

بصفتك مشرفًا في "إعلانات Google"، يمكنك إدارة دعوات وصول المستخدمين إلى حساب على "إعلانات Google". يتطلّب استدعاء واجهات برمجة التطبيقات هذه مستخدمًا مصادَقًا عليه لديه امتيازات الوصول إلى ADMIN في حساب العميل المستهدَف.

دعوة مستخدمين

ملاحظة: عند إنشاء دعوة، يجب تحديد عنوان بريد إلكتروني صالح وتعيين access_role مناسب. قد تُنشئ Google Ads API طلب موافقة جهات متعددة لإكمال هذا الإجراء. يمكنك الرجوع إلى دليل موافقة جهات متعدّدة لمزيد من المعلومات.

يمكنك إرسال دعوة عبر البريد الإلكتروني إلى مستخدم جديد كجزء من إدارة الوصول إلى حساب "إعلانات Google". يتم ذلك من خلال إنشاء CustomerUserAccessInvitation جديد باستخدام الإجراء MutateCustomerUserAccessInvitation من CustomerUserAccessInvitationService.

يجب أن يقبل المستخدم الذي تلقّى الدعوة عبر البريد الإلكتروني الدعوة يدويًا. يمكن للمستخدم أيضًا قبول الدعوة باستخدام عنوان بريد إلكتروني بديل. قد يستغرق تغيير الحالة من "في انتظار المراجعة" مدة تصل إلى 24 ساعة بعد قبول الدعوة. بعد التأكيد، يمكنك إدارة دور المستخدم وإذن وصوله كما هو موضّح في مقالة إدارة وصول المستخدمين.

إذا قرّرت 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
      

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::V26::Resources::CustomerUserAccessInvitation->new({
      emailAddress => $email_address,
      accessRole   => $access_role
    });

  # Create the user access invitation operation.
  my $invitation_operation =
    Google::Ads::GoogleAds::V26::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
      

إلغاء الدعوات

يمكنك إلغاء دعوة معلّقة من خلال تنفيذ عملية remove باستخدام طريقة MutateCustomerUserAccessInvitation في CustomerUserAccessInvitationService، مع تمرير اسم مورد الدعوة المطلوب إزالتها.

استرداد دعوات المستخدمين

يمكنك استرداد قائمة دعوات المستخدمين المعلّقة من خلال إنشاء عبارة لغة طلب البحث في "إعلانات Google" لطلب البحث عن جميع كيانات 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.