ניהול הזמנות של משתמשים לקבלת גישה

אדמינים ב-Google Ads יכולים לנהל את ההזמנות לגישת משתמשים לחשבון Google Ads. כדי להפעיל את ממשקי ה-API האלה, נדרש משתמש מאומת עם הרשאות גישה מסוג ADMIN בחשבון הלקוח הרלוונטי.

הזמנת משתמשים

אתם יכולים לשלוח הזמנה באימייל למשתמש חדש כחלק מניהול הגישה לחשבון Google Ads. כדי לעשות את זה, יוצרים CustomerUserAccessInvitation חדש באמצעות ה-method‏ MutateCustomerUserAccessInvitation של CustomerUserAccessInvitationService.

המשתמש שקיבל את ההזמנה באימייל צריך לאשר אותה באופן ידני. המשתמש יכול לאשר את ההזמנה גם באמצעות כתובת אימייל חלופית. יכול להיות שיעברו עד 24 שעות עד שהסטטוס ישתנה מ"בהמתנה" אחרי שההזמנה תאושר. אחרי האישור, תוכלו לנהל את התפקיד ואת הגישה של המשתמש, כמו שמתואר בקטע ניהול הגישה של המשתמשים.

אם Google קובעת שנדרש אישור ממספר משתמשים:

בקטע הקוד הבא אפשר לראות איך שולחים הזמנה:

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());
  }
}

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;
}

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
);

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}"
    )

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}'."

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;
}

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

ביטול הזמנות

כדי לבטל הזמנה בהמתנה, מפעילים פעולת 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

אפשר להוסיף תנאי סינון כדי לאחזר קבוצות משנה של הזמנות. לדוגמה, תרחיש נפוץ הוא לאחזר את רשימת ההזמנות למשתמשים שעדיין לא אושרו, על ידי סינון לפי customer_user_access_invitation.invitation_status = PENDING.

הקודם
ניהול הרשאות הגישה של משתמשים
הבא
קישור של חשבונות מוצרים