Section 15.1. Working with the AdWords API Web Services

15.1. Working with the AdWords API Web Services

Visual Studio.NET provides excellent tools for working with web services. When you reference a web service in Visual Studio, Visual Studio generates a proxy class. The proxy class for the web service uses the information provided by the WSDL file to encapsulate the XML SOAP input and output messages provided by the web service. You can use the members of this proxy class in your code just as you would the members of any other class, without having to know anything much about SOAP or web services.

15.1.1. Drilling Down

The application in this chapter displays all the campaigns associated with an account in a tree. Each campaign node on the tree can be expanded to show the AdGroups that are part of the campaign. You need to use a separate web service first to access an account, next to display the campaigns in the account, and finally to show the AdGroups within the campaigns.

Each of these three different web services need to be authenticated. In addition, a web service not at the top of the hierarchy needs an ID from the object that is above it to return values. For example, to access an AdGroup, your code needs to know the campaign ID of the campaign that contains the AdGroup. Similarly, to access keywords, your code needs to know the AdGroup ID of the AdGroup that contains the keywords. This relationship between objects and their containers is shown in Figure 15-1.

Figure 15-1. Objects need both account authentication and the identification code from an object in the hierarchy

The AdWords API web services used in this chapter, and their WSDL files, are as follows:

CampaignService

https://adwords.google.com/api/adwords/v2/CampaignService?wsdl

AdGroupService

https://adwords.google.com/api/adwords/v2/AdGroupService?wsdl

KeyWordService

https://adwords.google.com/api/adwords/v2/KeywordService?wsdl

15.1.2. Adding Web References

To add a web reference to one of the Google AdWords API web services, open a project I Visual Studio and choose Add Web Reference from the Project menu. The Ad Web Reference window, shown in Figure 15-2, will open.

Figure 15-2. When the Add Web Reference window opens, you can enter the URL for a web service WSDL file

Next, enter the address of the WSDL file for the web service in the URL box at the top of the window (the URL for the CampaignService WSDL is shown in Figure 15-3). Click the Go icon (to the right of the WSDL URL).

Figure 15-3. When Visual Studio connects to the WSDL file, the available web methods are displayed

When Visual Studio finds the WSDL file, it will parse it and display the methods associated with the web service in the Add Web Reference window. You can now add a proxy class that encapsulates the web service to your project by clicking Add Reference.

You should change the name of the web service reference in your project to something intelligible, rather than Visual Studio's suggestion. You can change this name in the Add Web Reference dialog (using the Web reference name text box) or after the web service reference has been added in Solution Explorer.

To drill down through the Google AdWords hierarchies, references must be added to multiple AdWords API web services. It's particularly important to change the names of the references to these web services, because if you let Visual Studio name them, it will attempt to name each the same thingcom.google.adwordswhich will cause errors, confusion, and delay.

Once the web service reference has been added to your project, you can see the web reference and its supporting files in Solution Explorer (Figure 15-4).

Figure 15-4. You can see the web reference files in Solution Explorer, including the Reference.cs file containing the actual proxy class code

To see all the supporting files for the web service reference and proxy class, you may need to click the Show All Files button in Solution Explorer.

You can repeat the process of entering the URL for the WSDL file for a web service to add references to the AdGroupService (Figure 15-5) and the KeywordService.

As the web service references are added to your project, and proxy classes generated, these appear in Solution Explorer (Figure 15-6).

With the web references added, and the proxy classes generated, you can also use Visual Studio's Object Browser to have a look at the proxy class members (Figure 15-7). This is a great way to easily find out about the facility that a web service makes availablemuch easier than reading the XML in the WSDL file, or even the documentation provided by Google with its web services.

Figure 15-5. If you look through the list of web methods, getAllAdGroups should return information about all AdGroups

Figure 15-6. It helps to name the web services intelligibly, rather than accepting Visual Studio's default name

Figure 15-7. You can find information about arguments and return values by using the Object Browser to inspect the proxy class for a web service

Using the Object Browser, you can easily see the methods available in the web service's proxy class. You can also find out the arguments each method takes, the type of the argument, and what the method returns.

15.1.3. Creating Objects Using the Proxy Classes

To use the members provided by a web service proxy class, an object based on the class must be instantiated.

First, as a convenience, include the namespace for each web service proxy class with a using directive:

     using AccountInfo.CampaignService;     using AccountInfo.AdGroupService;     using AccountInfo.KeywordService;

AccountInfo is the name of the project containing the web services.

Next, declare variables typed as each web service. These variables should be declared with sufficient scope so that you'll be able to use them when you need them (for example, in a Windows form class at the form class level). Use the new keyword to assign an object instance to each variable:

     CampaignServiceService service = new CampaignServiceService(  );     AdGroupServiceService ag = new AdGroupServiceService(  );     KeywordServiceService ks = new KeywordServiceService(  );