Codebeispiel für Clientlinks

In diesem Beispiel wird veranschaulicht, wie Sie die Anmeldeinformationen der Agentur verwenden, um einen Client einzuladen, und wie Clientanmeldeinformationen verwendet werden, um die Einladung anzunehmen. Führen Sie dieses Beispiel mehrmals im Wechsel zwischen Agentur- und Clientanmeldeinformationen aus, um die status Änderung zu aktualisieren und zu beobachten, z. B. von LinkPending zu LinkAccepted in Active.

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using Microsoft.BingAds.V13.CustomerManagement;
using Microsoft.BingAds;

namespace BingAdsExamplesLibrary.V13
{
    /// <summary>
    /// How to use agency credentials to invite a client, and use client credentials to accept the invitation.
    /// Run this sample multiple times alternating between agency and client credentials 
    /// to update and observe the status change, for example from LinkPending to LinkAccepted to Active. 
    /// </summary>
    public class ClientLinks : ExampleBase
    {
        // REQUIRED: The Client Account Id that you want to access.
        private long ClientAccountId = 0; 

        public override string Description
        {
            get { return "Manage Client | Customer Management V13"; }
        }

        public async override Task RunAsync(AuthorizationData authorizationData)
        {
            try
            {
                OutputStatusMessage("You must edit this example to provide the ClientAccountId for the client link." +
                    "When adding a client link, the client link's ManagingCustomerId is set to the CustomerId " +
                    "of the current authenticated user, who must be a Super Admin of the agency." +
                    "Login as an agency Super Admin user to send a client link invitation, or unlink an existing client link." +
                    "Login as a client Super Admin user to accept a client link invitation.");

                ApiEnvironment environment = ((OAuthDesktopMobileAuthCodeGrant)authorizationData.Authentication).Environment;

                CustomerManagementExampleHelper CustomerManagementExampleHelper = new CustomerManagementExampleHelper(
                    OutputStatusMessageDefault: this.OutputStatusMessage);
                CustomerManagementExampleHelper.CustomerManagementService = new ServiceClient<ICustomerManagementService>(
                    authorizationData: authorizationData,
                    environment: environment);

                UpdateClientLinksResponse updateClientLinksResponse = null;

                // Set the client link search criteria.

                var pageInfo = new Paging
                {
                    Index = 0, // The first page
                    Size = 100 // The first 100 client links for this page of results
                };

                var ordering = new OrderBy
                {
                    Field = OrderByField.Number,
                    Order = SortOrder.Ascending
                };

                var predicate = new Predicate
                {
                    Field = "ClientAccountId",
                    Operator = PredicateOperator.In,
                    Value = ClientAccountId.ToString(CultureInfo.InvariantCulture)
                };

                // Search for client links that match the criteria.

                OutputStatusMessage("-----\nSearchClientLinks:");
                var searchClientLinksResponse = (await CustomerManagementExampleHelper.SearchClientLinksAsync(
                    predicates: new[] { predicate },
                    ordering: new[] { ordering },
                    pageInfo: pageInfo));
                var clientLinks = searchClientLinksResponse?.ClientLinks;
                OutputStatusMessage("ClientLinks:");
                CustomerManagementExampleHelper.OutputArrayOfClientLink(clientLinks);

                // Determine whether the agency is already managing the specified client account. 
                // If a link exists with status either Active, LinkInProgress, LinkPending, 
                // UnlinkInProgress, or UnlinkPending, the agency may not initiate a duplicate client link.

                ClientLink clientLink;
                var newLinkRequired = true;

                if (clientLinks.Count > 0)
                {
                    clientLink = clientLinks[0];
                    OutputStatusMessage("Using the first client link as an example.");
                    OutputStatusMessage(string.Format("Current ClientLink Status: {0}.", clientLink.Status));

                    switch (clientLink.Status)
                    {
                        // The agency may choose to initiate the unlink process, 
                        // which would terminate the existing relationship with the client. 
                        case ClientLinkStatus.Active:
                            clientLink.Status = ClientLinkStatus.UnlinkRequested;
                            OutputStatusMessage("-----\nUpdateClientLinks:");
                            updateClientLinksResponse = await CustomerManagementExampleHelper.UpdateClientLinksAsync(
                                clientLinks: new[] { clientLink });
                            OutputStatusMessage("UnlinkRequested");
                            newLinkRequired = false;
                            break;
                        // Waiting on a system status transition or waiting for the StartDate.
                        case ClientLinkStatus.LinkAccepted:
                            OutputStatusMessage("The status is transitioning towards LinkInProgress");
                            newLinkRequired = false;
                            break;
                        // Waiting on a system status transition.
                        case ClientLinkStatus.LinkInProgress:
                            OutputStatusMessage("The status is transitioning towards Active");
                            newLinkRequired = false;
                            break;
                        // When the status is LinkPending, either the agency or client may update the status.
                        // The agency may choose to cancel the client link invitation; however, in this example 
                        // the client will accept the invitation. 
                        // If the client does not accept or decline the invitation within 30 days, and if the agency
                        // does not update the status to LinkCanceled, the system updates the status to LinkExpired.
                        case ClientLinkStatus.LinkPending:
                            clientLink.Status = ClientLinkStatus.LinkAccepted;
                            OutputStatusMessage("-----\nUpdateClientLinks:");
                            updateClientLinksResponse = await CustomerManagementExampleHelper.UpdateClientLinksAsync(
                                clientLinks: new[] { clientLink });
                            OutputStatusMessage("LinkAccepted");
                            newLinkRequired = false;
                            break;
                        // Waiting on a system status transition.
                        case ClientLinkStatus.UnlinkInProgress:
                            OutputStatusMessage("The status is transitioning towards Inactive");
                            newLinkRequired = false;
                            break;
                        // Waiting on a system status transition.
                        case ClientLinkStatus.UnlinkPending:
                            OutputStatusMessage("The status is transitioning towards Inactive");
                            newLinkRequired = false;
                            break;
                        // The link lifecycle has ended.  
                        default:
                            OutputStatusMessage("A new client link invitation is required");
                            break;
                    }
                    
                    // Output errors if any occurred when updating the client link.

                    if (updateClientLinksResponse != null)
                    {
                        OutputStatusMessage("OperationErrors:");
                        CustomerManagementExampleHelper.OutputArrayOfOperationError(updateClientLinksResponse.OperationErrors);
                        OutputStatusMessage("PartialErrors:");
                        foreach (List<OperationError> operationErrors in updateClientLinksResponse.PartialErrors)
                        {
                            CustomerManagementExampleHelper.OutputArrayOfOperationError(operationErrors);
                        }
                    }
                }

                // If no links exist between the agency and specified client account, or a link exists with status  
                // either Inactive, LinkCanceled, LinkDeclined, LinkExpired, or LinkFailed, then the agency must
                // initiate a new client link.

                if (newLinkRequired)
                {
                    clientLink = new ClientLink
                    {
                        ClientEntityId = ClientAccountId,
                        ManagingCustomerId = authorizationData.CustomerId,
                        IsBillToClient = true,
                        Name = "My Client Link",
                        StartDate = null,
                        SuppressNotification = true
                    };

                    OutputStatusMessage("-----\nAddClientLinks:");
                    var addClientLinksResponse = await CustomerManagementExampleHelper.AddClientLinksAsync(
                        clientLinks: new[] { clientLink });
                    OutputStatusMessage("OperationErrors:");
                    CustomerManagementExampleHelper.OutputArrayOfOperationError(addClientLinksResponse.OperationErrors);
                    OutputStatusMessage("PartialErrors:");
                    foreach (List<OperationError> operationErrors in addClientLinksResponse.PartialErrors)
                    {
                        CustomerManagementExampleHelper.OutputArrayOfOperationError(operationErrors);
                    }
                }

                // Output the client links after any status updates above.

                OutputStatusMessage("-----\nSearchClientLinks:");
                searchClientLinksResponse = (await CustomerManagementExampleHelper.SearchClientLinksAsync(
                    predicates: new[] { predicate },
                    ordering: new[] { ordering },
                    pageInfo: pageInfo));
                clientLinks = searchClientLinksResponse?.ClientLinks;
                OutputStatusMessage("ClientLinks:");
                CustomerManagementExampleHelper.OutputArrayOfClientLink(clientLinks);
            }
            // Catch authentication exceptions
            catch (OAuthTokenRequestException ex)
            {
                OutputStatusMessage(string.Format("Couldn't get OAuth tokens. Error: {0}. Description: {1}", ex.Details.Error, ex.Details.Description));
            }
            // Catch Customer Management service exceptions
            catch (FaultException<Microsoft.BingAds.V13.CustomerManagement.AdApiFaultDetail> ex)
            {
                OutputStatusMessage(string.Join("; ", ex.Detail.Errors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
            }
            catch (FaultException<Microsoft.BingAds.V13.CustomerManagement.ApiFault> ex)
            {
                OutputStatusMessage(string.Join("; ", ex.Detail.OperationErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
            }
            catch (Exception ex)
            {
                OutputStatusMessage(ex.Message);
            }
        }
    }
}

package com.microsoft.bingads.examples.v13;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.customermanagement.*;

// How to use agency credentials to invite a client, 
// and use client credentials to accept the invitation. 
// Run this sample multiple times alternating between agency and client credentials 
// to update and observe the status change, for example from LinkPending to LinkAccepted to Active. 

public class ClientLinks extends ExampleBase {

    static AuthorizationData authorizationData; 
    
    // REQUIRED: The Client Account Id that you want to access. 
    private static long ClientAccountId = 0; 
    
    public static void main(java.lang.String[] args) {
     
        try
        {
            authorizationData = getAuthorizationData(); 
            
            CustomerManagementExampleHelper.CustomerManagementService = new ServiceClient<ICustomerManagementService>(
                    authorizationData, 
                    API_ENVIRONMENT,
                    ICustomerManagementService.class);
            
            outputStatusMessage("You must edit this example to provide the ClientAccountId for the client link." +
                    "When adding a client link, the client link's ManagingCustomerId is set to the CustomerId " +
                    "of the current authenticated user, who must be a Super Admin of the agency." +
                    "Login as an agency Super Admin user to send a client link invitation, or unlink an existing client link." +
                    "Login as a client Super Admin user to accept a client link invitation.");
 
            UpdateClientLinksResponse updateClientLinksResponse = null;

            // Set the client link search criteria.

            Paging pageInfo = new Paging();
            pageInfo.setIndex(0);    // The first page
            pageInfo.setSize(100);   // The first 100 client links for this page of results
            
            ArrayOfOrderBy ordering = new ArrayOfOrderBy();
            OrderBy orderBy = new OrderBy();
            orderBy.setField(OrderByField.NUMBER);
            orderBy.setOrder(SortOrder.ASCENDING);
            ordering.getOrderBies().add(orderBy);

            ArrayOfPredicate predicates = new ArrayOfPredicate();
            Predicate predicate = new Predicate();
            predicate.setField("ClientAccountId");
            predicate.setOperator(PredicateOperator.IN);
            predicate.setValue("" + ClientAccountId);
            predicates.getPredicates().add(predicate);
            
            // Search for client links that match the criteria.

            outputStatusMessage("-----\nSearchClientLinks:");
            ArrayOfClientLink clientLinks = CustomerManagementExampleHelper.searchClientLinks(
                predicates,
                ordering,
                pageInfo).getClientLinks();
            outputStatusMessage("ClientLinks:");
            CustomerManagementExampleHelper.outputArrayOfClientLink(clientLinks);

            // Determine whether the agency is already managing the specified client account. 
            // If a link exists with status either Active, LinkInProgress, LinkPending, 
            // UnlinkInProgress, or UnlinkPending, the agency may not initiate a duplicate client link.

            ClientLink clientLink;
            boolean newLinkRequired = true;

            if (clientLinks.getClientLinks().size() > 0)
            {
                clientLink = clientLinks.getClientLinks().get(0);
                outputStatusMessage("Using the first client link as an example.");
                outputStatusMessage(String.format("Current ClientLink Status: %s.", clientLink.getStatus()));
                
                ArrayOfClientLink updateClientLinks = new ArrayOfClientLink();                
                
                switch (clientLink.getStatus())
                {
                    // The agency may choose to initiate the unlink process, 
                    // which would terminate the existing relationship with the client. 
                    case ACTIVE:
                        clientLink.setStatus(ClientLinkStatus.UNLINK_REQUESTED);
                        updateClientLinks.getClientLinks().add(clientLink);
                        outputStatusMessage("-----\nUpdateClientLinks:");
                        updateClientLinksResponse = CustomerManagementExampleHelper.updateClientLinks(
                                updateClientLinks);
                        outputStatusMessage("UpdateClientLinks : UnlinkRequested.");
                        newLinkRequired = false;
                        break;
                    // Waiting on a system status transition or waiting for the StartDate.
                    case LINK_ACCEPTED:
                        outputStatusMessage("The status is transitioning towards LinkInProgress.");
                        newLinkRequired = false;
                        break;
                    // Waiting on a system status transition.
                    case LINK_IN_PROGRESS:
                        outputStatusMessage("The status is transitioning towards Active.");
                        newLinkRequired = false;
                        break;
                    // When the status is LinkPending, either the agency or client may update the status.
                    // The agency may choose to cancel the client link invitation; however, in this example 
                    // the client will accept the invitation. 
                    // If the client does not accept or decline the invitation within 30 days, and if the agency
                    // does not update the status to LinkCanceled, the system updates the status to LinkExpired.
                    case LINK_PENDING:
                        clientLink.setStatus(ClientLinkStatus.LINK_ACCEPTED);
                        updateClientLinks.getClientLinks().add(clientLink);
                        outputStatusMessage("-----\nUpdateClientLinks:");
                        updateClientLinksResponse = CustomerManagementExampleHelper.updateClientLinks(
                                updateClientLinks);
                        outputStatusMessage("UpdateClientLinks: LinkAccepted.");
                        newLinkRequired = false;
                        break;
                    // Waiting on a system status transition.
                    case UNLINK_IN_PROGRESS:
                        outputStatusMessage("The status is transitioning towards Inactive.");
                        newLinkRequired = false;
                        break;
                    // Waiting on a system status transition.
                    case UNLINK_PENDING:
                        outputStatusMessage("The status is transitioning towards Inactive.");
                        newLinkRequired = false;
                        break;
                    // The link lifecycle has ended.  
                    default:
                        outputStatusMessage("A new client link invitation is required.");
                        break;
                }

                // Print errors if any occurred when updating the client link.
                if (updateClientLinksResponse != null)
                {
                    outputStatusMessage("OperationErrors:");   
                    CustomerManagementExampleHelper.outputArrayOfOperationError(updateClientLinksResponse.getOperationErrors());   
                    outputStatusMessage("PartialErrors:");
                    for(ArrayOfOperationError operationErrors: updateClientLinksResponse.getPartialErrors().getArrayOfOperationErrors())
                    {
                        CustomerManagementExampleHelper.outputArrayOfOperationError(operationErrors);   
                    }
                }
            }

            // If no links exist between the agency and specified client account, or a link exists with status  
            // either Inactive, LinkCanceled, LinkDeclined, LinkExpired, or LinkFailed, then the agency must
            // initiate a new client link.

            if(newLinkRequired)
            {
                clientLink = new ClientLink();
                clientLink.setClientEntityId(ClientAccountId);
                clientLink.setManagingCustomerId(authorizationData.getCustomerId());
                clientLink.setIsBillToClient(true);
                clientLink.setName("My Client Link");
                clientLink.setStartDate(null);
                clientLink.setSuppressNotification(true);

                ArrayOfClientLink addClientLinks = new ArrayOfClientLink();
                addClientLinks.getClientLinks().add(clientLink);
                
                outputStatusMessage("-----\nAddClientLinks:");
                AddClientLinksResponse addClientLinksResponse = CustomerManagementExampleHelper.addClientLinks(
                        addClientLinks);
                outputStatusMessage("OperationErrors:");                    
                CustomerManagementExampleHelper.outputArrayOfOperationError(addClientLinksResponse.getOperationErrors());   
                outputStatusMessage("PartialErrors:");
                for(ArrayOfOperationError operationErrors: addClientLinksResponse.getPartialErrors().getArrayOfOperationErrors())
                {
                    CustomerManagementExampleHelper.outputArrayOfOperationError(operationErrors);   
                }
            }

            // Output the client links after any status updates above.

            outputStatusMessage("-----\nSearchClientLinks:");
            clientLinks = CustomerManagementExampleHelper.searchClientLinks(
                predicates,
                ordering,
                pageInfo).getClientLinks();
            outputStatusMessage("ClientLinks:");
            CustomerManagementExampleHelper.outputArrayOfClientLink(clientLinks);
        } 
        catch (Exception ex) {
            String faultXml = ExampleExceptionHelper.getBingAdsExceptionFaultXml(ex, System.out);
            outputStatusMessage(faultXml);
            String message = ExampleExceptionHelper.handleBingAdsSDKException(ex, System.out);
            outputStatusMessage(message);
        }
    }
}

<?php

use Microsoft\MsAds\Rest\ApiException;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\ClientLink;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\ClientLinkStatus;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\AddClientLinksRequest;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\UpdateClientLinksRequest;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\SearchClientLinksRequest;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\Paging;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\Predicate;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\PredicateOperator;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\OrderBy;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\OrderByField;
use Microsoft\MsAds\Rest\Model\CustomerManagementService\SortOrder;
use Microsoft\MsAds\Rest\Test\RestApiTestBase;

class ClientLinksTest extends RestApiTestBase
{

    // You must edit this example to provide the ClientAccountId for the client link.
    // When adding a client link, the client link's ManagingCustomerId is set to the CustomerId
    // of the current authenticated user, who must be a Super Admin of the agency.
    // Login as an agency Super Admin user to send a client link invitation, or unlink an existing client link.
    // Login as a client Super Admin user to accept a client link invitation.
    protected int $clientAccountId = 0; // Set this to a valid client account ID

    /**
     * @throws ApiException
     */
    public function testSearchClientLinks()
    {
        print("-----\r\nSearchClientLinks:\r\n");
        $paging = new Paging();
        $paging->setIndex(0);
        $paging->setSize(100);

        $predicate = new Predicate();
        $predicate->setField("ClientAccountId");
        $predicate->setOperator(PredicateOperator::IN);
        $predicate->setValue((string)$this->clientAccountId);

        $orderBy = new OrderBy();
        $orderBy->setField(OrderByField::NUMBER);
        $orderBy->setOrder(SortOrder::ASCENDING);

        $request = new SearchClientLinksRequest([
            'Predicates' => [$predicate],
            'Ordering' => [$orderBy],
            'PageInfo' => $paging
        ]);

        $response = self::$customerManagementServiceApi->searchClientLinks($request);
        $clientLinks = $response->getClientLinks();
        print("ClientLinks:\r\n");
        print_r($clientLinks);
        self::assertIsArray($clientLinks);
        return $clientLinks;
    }

    /**
     * @depends testSearchClientLinks
     * @throws ApiException
     */
    public function testAddClientLink($clientLinks)
    {
        $newLinkRequired = true;
        $existingLink = null;
        if (!empty($clientLinks)) {
            $existingLink = $clientLinks[0];
            if (in_array($existingLink->getStatus(), [
                ClientLinkStatus::ACTIVE,
                ClientLinkStatus::LINK_IN_PROGRESS,
                ClientLinkStatus::LINK_PENDING,
                ClientLinkStatus::UNLINK_IN_PROGRESS,
                ClientLinkStatus::UNLINK_PENDING,
                ClientLinkStatus::LINK_ACCEPTED
            ])) {
                $newLinkRequired = false;
            }
        }

        if ($newLinkRequired) {
            $clientLink = new ClientLink();
            $clientLink->setClientEntityId($this->clientAccountId);
            $clientLink->setManagingCustomerId(self::CUSTOMER_ID);
            $clientLink->setIsBillToClient(true);
            $clientLink->setName("My Client Link" . self::generateRandomAlphaNumeric());
            $clientLink->setStartDate(null);
            $clientLink->setSuppressNotification(false);

            print("-----\r\nAddClientLinks:\r\n");
            $request = new AddClientLinksRequest([
                'ClientLinks' => [$clientLink]
            ]);
            $response = self::$customerManagementServiceApi->addClientLinks($request);
            print("OperationErrors:\r\n");
            print_r($response->getOperationErrors());
            print("PartialErrors:\r\n");
            print_r($response->getPartialErrors());
            self::assertEmpty($response->getOperationErrors());
        } else {
            print("A new client link is not required.\r\n");
        }
    }

    /**
     * @depends testSearchClientLinks
     * @throws ApiException
     */
    public function testUpdateClientLink($clientLinks)
    {
        if (empty($clientLinks)) {
            self::markTestSkipped('No client links to update.');
        }
        $clientLink = $clientLinks[0];
        $status = $clientLink->getStatus();
        $update = false;
        if ($status === ClientLinkStatus::ACTIVE) {
            $clientLink->setStatus(ClientLinkStatus::UNLINK_REQUESTED);
            $update = true;
        } elseif ($status === ClientLinkStatus::LINK_PENDING) {
            $clientLink->setStatus(ClientLinkStatus::LINK_ACCEPTED);
            $update = true;
        }
        if ($update) {
            print("-----\r\nUpdateClientLinks:\r\n");
            $request = new UpdateClientLinksRequest([
                'ClientLinks' => [$clientLink]
            ]);
            $response = self::$customerManagementServiceApi->updateClientLinks($request);
            print("OperationErrors:\r\n");
            print_r($response->getOperationErrors());
            print("PartialErrors:\r\n");
            print_r($response->getPartialErrors());
            self::assertEmpty($response->getOperationErrors());
        } else {
            print("No update required for client link status: $status\r\n");
        }
    }
}

from auth_helper import *
from openapi_client.models.customer import *
import uuid

def main(authorization_data):
    try:
        # Add client links
        client_link = ClientLink(
            client_entity_id=authorization_data.account_id,
            managing_customer_id=authorization_data.customer_id,
            is_bill_to_client=True,
            name="Test client link" + str(uuid.uuid4()),
            start_date=None,
            suppress_notification=False
        )

        add_request = AddClientLinksRequest(client_links=[client_link])
        add_response = customer_service.add_client_links(add_client_links_request=add_request)
        assert isinstance(add_response,
                          AddClientLinksResponse), "add_response is not an instance of AddInsertionOrderResponse"

        # Search client links
        paging = Paging(index=0, size=100)
        predicate = Predicate(
            field='ClientAccountId',
            operator=PredicateOperator.IN,
            value=authorization_data.account_id
        )
        order_by = OrderBy(field=OrderByField.NUMBER, order=SortOrder.ASCENDING)

        request = SearchClientLinksRequest(
            predicates=[predicate],
            ordering=[order_by],
            page_info=paging
        )
        response = customer_service.search_client_links(search_client_links_request=request)
        client_links = response.client_links
        assert (len(client_links) > 0)
    except Exception as ex:
        print(f"Error occurred: {str(ex)}")


if __name__ == '__main__':
    print("Loading the web service client...")

    authorization_data = AuthorizationData(
        account_id=None,
        customer_id=None,
        developer_token=DEVELOPER_TOKEN,
        authentication=None,
    )

    authenticate(authorization_data)

    customer_service = ServiceClient(
        service='CustomerManagementService',
        version=13,
        authorization_data=authorization_data,
        environment=ENVIRONMENT,
    )

    main(authorization_data)

Siehe auch

Erste Schritte mit der Bing Ads-API