MigrateToExtensionSettings.vb

' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201809

Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
    ''' <summary>
    ''' This code example migrates your feed based sitelinks at campaign level to
    ''' use extension settings. To learn more about extensionsettings, see
    ''' https://developers.google.com/adwords/api/docs/guides/extension-settings.
    ''' To learn more about migrating Feed based extensions to extension
    ''' settings, see
    ''' https://developers.google.com/adwords/api/docs/guides/migrate-to-extension-settings.
    ''' </summary>
    ''' <remarks>This code example doesn't migrate scheduling or feeditem-level campaign, adgroup,
    ''' keyword, Or geo targeting settings.</remarks>
    Public Class MigrateToExtensionSettings
        Inherits ExampleBase

        ''' <summary>
        ''' The placeholder type for sitelinks. See
        ''' https://developers.google.com/adwords/api/docs/appendix/placeholders for
        ''' the list of all supported placeholder types.
        ''' </summary>
        Private Const PLACEHOLDER_TYPE_SITELINKS As Integer = 1

        ''' <summary>
        ''' Holds the placeholder field IDs for sitelinks. See
        ''' https://developers.google.com/adwords/api/docs/appendix/placeholders for
        ''' the list of all supported placeholder types.
        ''' </summary>
        Private Class SiteLinkFields
            Public Const TEXT As Long = 1
            Public Const URL As Long = 2
            Public Const LINE2 As Long = 3
            Public Const LINE3 As Long = 4
            Public Const FINAL_URLS As Long = 5
            Public Const FINAL_MOBILE_URLS As Long = 6
            Public Const TRACKING_URL_TEMPLATE As Long = 7
        End Class

        ''' <summary>
        ''' A sitelink object read from a feed.
        ''' </summary>
        Private Class SiteLinkFromFeed
            ''' <summary>
            ''' The feed ID.
            ''' </summary>
            Private feedIdField As Long

            ''' <summary>
            ''' The feed item ID.
            ''' </summary>
            Private feedItemIdField As Long

            ''' <summary>
            ''' The sitelink text.
            ''' </summary>
            Private textField As String

            ''' <summary>
            ''' The sitelink URL.
            ''' </summary>
            Private urlField As String

            ''' <summary>
            ''' The sitelink final URLs.
            ''' </summary>
            Private finalUrlsField As String()

            ''' <summary>
            ''' The sitelink final Mobile URLs.
            ''' </summary>
            Private finalMobileUrlsField As String()

            ''' <summary>
            ''' The sitelink tracking URL template.
            ''' </summary>
            Private trackingUrlTemplateField As String

            ''' <summary>
            ''' The sitelink line2 details.
            ''' </summary>
            Private line2Field As String

            ''' <summary>
            ''' The sitelink line3 details.
            ''' </summary>
            Private line3Field As String

            ''' <summary>
            ''' Gets or sets the feed ID.
            ''' </summary>
            Public Property FeedId As Long
                Get
                    Return feedIdField
                End Get
                Set(ByVal value As Long)
                    feedIdField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the feed item ID.
            ''' </summary>
            Public Property FeedItemId As Long
                Get
                    Return feedItemIdField
                End Get
                Set(ByVal value As Long)
                    feedItemIdField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the sitelink text.
            ''' </summary>
            Public Property Text As String
                Get
                    Return textField
                End Get
                Set(ByVal value As String)
                    textField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the sitelink URL.
            ''' </summary>
            Public Property Url As String
                Get
                    Return urlField
                End Get
                Set(ByVal value As String)
                    urlField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the sitelink final URLs.
            ''' </summary>
            Public Property FinalUrls As String()
                Get
                    Return finalUrlsField
                End Get
                Set(ByVal value As String())
                    finalUrlsField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the sitelink final Mobile URLs.
            ''' </summary>
            Public Property FinalMobileUrls As String()
                Get
                    Return finalMobileUrlsField
                End Get
                Set(ByVal value As String())
                    finalMobileUrlsField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the tracking URL template.
            ''' </summary>
            Public Property TrackingUrlTemplate As String
                Get
                    Return trackingUrlTemplateField
                End Get
                Set(ByVal value As String)
                    trackingUrlTemplateField = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the sitelink line2 details.
            ''' </summary>
            Public Property Line2 As String
                Get
                    Return line2Field
                End Get
                Set(ByVal value As String)
                    line2Field = value
                End Set
            End Property

            ''' <summary>
            ''' Gets or sets the sitelink line3 details.
            ''' </summary>
            Public Property Line3 As String
                Get
                    Return line3Field
                End Get
                Set(ByVal value As String)
                    line3Field = value
                End Set
            End Property
        End Class

        ''' <summary>
        ''' Main method, to run this code example as a standalone application.
        ''' </summary>
        ''' <param name="args">The command line arguments.</param>
        Public Shared Sub Main(ByVal args As String())
            Dim codeExample As New MigrateToExtensionSettings
            Console.WriteLine(codeExample.Description)
            Try
                codeExample.Run(New AdWordsUser)
            Catch e As Exception
                Console.WriteLine("An exception occurred while running this code example. {0}",
                                  ExampleUtilities.FormatException(e))
            End Try
        End Sub

        ''' <summary>
        ''' Returns a description about the code example.
        ''' </summary>
        Public Overrides ReadOnly Property Description() As String
            Get
                Return _
                    "This code example migrates your feed based sitelinks at campaign level to " &
                    "use extension settings. To learn more about extensionsettings, see " &
                    "https://developers.google.com/adwords/api/docs/guides/extension-settings. " &
                    "To learn more about migrating Feed based extensions to extension settings, " &
                    "see https://developers.google.com/adwords/api/docs/guides/migrate-to-extension-settings."
            End Get
        End Property

        ''' <summary>
        ''' Runs the code example.
        ''' </summary>
        ''' <param name="user">The AdWords user.</param>
        Public Sub Run(ByVal user As AdWordsUser)
            ' Get all the feeds from the user account.
            Dim feeds As Feed() = GetFeeds(user)

            For Each feed As Feed In feeds
                ' Retrieve all the sitelinks from the current feed.
                Dim feedItems As Dictionary(Of Long, SiteLinkFromFeed) =
                        GetSiteLinksFromFeed(user, feed.id)

                ' Get all the instances where a sitelink from this feed has been added
                ' to a campaign.
                Dim campaignFeeds As CampaignFeed() = GetCampaignFeeds(user, feed,
                                                                       PLACEHOLDER_TYPE_SITELINKS)

                If Not campaignFeeds Is Nothing Then
                    Dim allFeedItemsToDelete As New HashSet(Of Long)()

                    For Each campaignFeed As CampaignFeed In campaignFeeds
                        ' Retrieve the sitelinks that have been associated with this
                        ' campaign.
                        Dim feedItemIds As List(Of Long) = GetFeedItemsForCampaign(campaignFeed)
                        Dim platformRestrictions As ExtensionSettingPlatform =
                                GetPlatformRestrictionsForCampaign(campaignFeed)

                        If feedItemIds.Count = 0 Then
                            Console.WriteLine(
                                "Migration skipped for campaign feed with campaign ID {0} " &
                                "and feed ID {1} because no mapped feed item IDs were found in " &
                                "the campaign feed's matching function.", campaignFeed.campaignId,
                                campaignFeed.feedId)
                        Else
                            ' Delete the campaign feed that associates the sitelinks from the
                            ' feed to the campaign.
                            DeleteCampaignFeed(user, campaignFeed)

                            ' Create extension settings instead of sitelinks.
                            CreateExtensionSetting(user, feedItems, campaignFeed.campaignId,
                                                   feedItemIds,
                                                   platformRestrictions)

                            ' Mark the sitelinks from the feed for deletion.
                            allFeedItemsToDelete.UnionWith(feedItemIds)
                        End If
                    Next
                    ' Delete all the sitelinks from the feed.
                    DeleteOldFeedItems(user, New List(Of Long)(allFeedItemsToDelete), feed.id)
                End If
            Next
        End Sub

        ''' <summary>
        ''' Gets the site links from a feed.
        ''' </summary>
        ''' <param name="user">The user that owns the feed.</param>
        ''' <param name="feedId">The feed ID.</param>
        ''' <returns>A dictionary of sitelinks from the feed, with key as the feed
        ''' item ID, and value as the sitelink.</returns>
        Private Function GetSiteLinksFromFeed(ByVal user As AdWordsUser, ByVal feedId As Long) As _
            Dictionary(Of Long, SiteLinkFromFeed)
            Dim siteLinks As New Dictionary(Of Long, SiteLinkFromFeed)()

            ' Retrieve all the feed items from the feed.
            Dim feedItems As FeedItem() = GetFeedItems(user, feedId)

            ' Retrieve the feed's attribute mapping.
            Dim feedMappings As Dictionary(Of Long, HashSet(Of Long)) =
                    GetFeedMapping(user, feedId, PLACEHOLDER_TYPE_SITELINKS)

            If Not feedItems Is Nothing Then
                For Each feedItem As FeedItem In feedItems
                    Dim sitelinkFromFeed As New SiteLinkFromFeed()
                    sitelinkFromFeed.FeedId = feedItem.feedId
                    sitelinkFromFeed.FeedItemId = feedItem.feedItemId

                    For Each attributeValue As FeedItemAttributeValue In feedItem.attributeValues
                        ' This attribute hasn't been mapped to a field.
                        If Not feedMappings.ContainsKey(attributeValue.feedAttributeId) Then
                            Continue For
                        End If
                        ' Get the list of all the fields to which this attribute has been mapped.
                        For Each fieldId As Long In feedMappings(attributeValue.feedAttributeId)
                            ' Read the appropriate value depending on the ID of the mapped
                            ' field.
                            Select Case fieldId
                                Case SiteLinkFields.TEXT
                                    sitelinkFromFeed.Text = attributeValue.stringValue

                                Case SiteLinkFields.URL
                                    sitelinkFromFeed.Url = attributeValue.stringValue

                                Case SiteLinkFields.FINAL_URLS
                                    sitelinkFromFeed.FinalUrls = attributeValue.stringValues

                                Case SiteLinkFields.FINAL_MOBILE_URLS
                                    sitelinkFromFeed.FinalMobileUrls = attributeValue.stringValues

                                Case SiteLinkFields.TRACKING_URL_TEMPLATE
                                    sitelinkFromFeed.TrackingUrlTemplate =
                                        attributeValue.stringValue

                                Case SiteLinkFields.LINE2
                                    sitelinkFromFeed.Line2 = attributeValue.stringValue

                                Case SiteLinkFields.LINE3
                                    sitelinkFromFeed.Line3 = attributeValue.stringValue
                            End Select
                        Next
                    Next
                    siteLinks.Add(feedItem.feedItemId, sitelinkFromFeed)
                Next
            End If
            Return siteLinks
        End Function

        ''' <summary>
        ''' Gets the feed mapping for a feed.
        ''' </summary>
        ''' <param name="user">The user that owns the feed.</param>
        ''' <param name="feedId">The feed ID.</param>
        ''' <param name="placeHolderType">Type of the place holder for which feed
        ''' mappings should be retrieved.</param>
        ''' <returns>A dictionary, with key as the feed attribute ID, and value as
        ''' the set of all fields which the attribute has a mapping to.</returns>
        Private Function GetFeedMapping(ByVal user As AdWordsUser, ByVal feedId As Long,
                                        ByVal placeHolderType As Long) _
            As Dictionary(Of Long, HashSet(Of Long))
            Using feedMappingService As FeedMappingService = DirectCast(
                user.GetService(
                    AdWordsService.v201809.FeedMappingService),
                FeedMappingService)
                Dim page As FeedMappingPage = feedMappingService.query(
                    String.Format(
                        "SELECT FeedMappingId, AttributeFieldMappings where FeedId='{0}' and " &
                        "PlaceholderType={1} and Status='ENABLED'", feedId, placeHolderType))

                Dim attributeMappings As New Dictionary(Of Long, HashSet(Of Long))()

                If Not (page.entries Is Nothing) Then
                    ' Normally, a feed attribute is mapped only to one field. However,
                    ' you may map it to more than one field if needed.
                    For Each feedMapping As FeedMapping In page.entries
                        For Each attributeMapping As AttributeFieldMapping In _
                            feedMapping.attributeFieldMappings
                            If Not attributeMappings.ContainsKey(attributeMapping.feedAttributeId) _
                                Then
                                attributeMappings(attributeMapping.feedAttributeId) =
                                    New HashSet(Of Long)()
                            End If
                            attributeMappings(attributeMapping.feedAttributeId).Add(
                                attributeMapping.fieldId)
                        Next
                    Next
                End If
                Return attributeMappings
            End Using
        End Function

        ''' <summary>
        ''' Gets the feeds.
        ''' </summary>
        ''' <param name="user">The user for which feeds are retrieved.</param>
        ''' <returns>The list of feeds.</returns>
        Private Function GetFeeds(ByVal user As AdWordsUser) As Feed()
            ' TODO(b/67949201): This needs to handle paging
            Using feedService As FeedService = DirectCast(
                user.GetService(
                    AdWordsService.v201809.FeedService),
                FeedService)
                Dim page As FeedPage = feedService.query("SELECT Id, Name, Attributes where " &
                                                         "Origin='USER' and FeedStatus='ENABLED'")
                Return page.entries
            End Using
        End Function

        ''' <summary>
        ''' Gets the feed items in a feed.
        ''' </summary>
        ''' <param name="user">The user that owns the feed.</param>
        ''' <param name="feedId">The feed ID.</param>
        ''' <returns>The list of feed items in the feed.</returns>
        Private Function GetFeedItems(ByVal user As AdWordsUser, ByVal feedId As Long) As FeedItem()
            ' TODO(b/67949201): This needs to handle paging
            Using FeedItemService As FeedItemService = DirectCast(
                user.GetService(
                    AdWordsService.v201809.FeedItemService),
                FeedItemService)
                Dim page As FeedItemPage =
                        FeedItemService.query(String.Format("SELECT FeedItemId, AttributeValues " &
                                                            "WHERE Status = 'ENABLED'" &
                                                            " AND FeedId = '{0}'",
                                                            feedId))
                Return page.entries
            End Using
        End Function

        ''' <summary>
        ''' Deletes the old feed items for which extension settings have been
        ''' created.
        ''' </summary>
        ''' <param name="user">The user that owns the feed items.</param>
        ''' <param name="feedItemIds">IDs of the feed items to be removed.</param>
        ''' <param name="feedId">ID of the feed that holds the feed items.</param>
        Private Sub DeleteOldFeedItems(ByVal user As AdWordsUser,
                                       ByVal feedItemIds As List(Of Long),
                                       ByVal feedId As Long)
            If feedItemIds.Count = 0 Then
                Return
            End If
            Dim operations As New List(Of FeedItemOperation)()
            For Each feedItemId As Long In feedItemIds
                Dim operation As New FeedItemOperation()
                operation.operator = [Operator].REMOVE

                operation.operand = New FeedItem()
                operation.operand.feedItemId = feedItemId
                operation.operand.feedId = feedId

                operations.Add(operation)
            Next
            Using feedItemService As FeedItemService = DirectCast(
                user.GetService(
                    AdWordsService.v201809.FeedItemService),
                FeedItemService)
                feedItemService.mutate(operations.ToArray())
                Return
            End Using
        End Sub

        ''' <summary>
        ''' Creates the extension setting fo a list of feed items.
        ''' </summary>
        ''' <param name="user">The user for which extension settings are created.
        ''' </param>
        ''' <param name="feedItems">The list of all feed items.</param>
        ''' <param name="campaignId">ID of the campaign to which extension settings
        ''' are added.</param>
        ''' <param name="feedItemIds">IDs of the feed items for which extension
        ''' settings should be created.</param>
        ''' <param name="platformRestrictions">The platform restrictions for the
        ''' extension setting.</param>
        Private Sub CreateExtensionSetting(ByVal user As AdWordsUser, ByVal feedItems As _
                                              Dictionary(Of Long, SiteLinkFromFeed),
                                           ByVal campaignId As Long,
                                           ByVal feedItemIds As List(Of Long),
                                           ByVal platformRestrictions As ExtensionSettingPlatform)
            Dim extensionSetting As New CampaignExtensionSetting()
            extensionSetting.campaignId = campaignId
            extensionSetting.extensionType = FeedType.SITELINK
            extensionSetting.extensionSetting = New ExtensionSetting()

            Dim extensionFeedItems As New List(Of ExtensionFeedItem)()

            For Each feedItemId As Long In feedItemIds
                Dim feedItem As SiteLinkFromFeed = feedItems(feedItemId)

                Dim newFeedItem As New SitelinkFeedItem()
                newFeedItem.sitelinkText = feedItem.Text
                newFeedItem.sitelinkUrl = feedItem.Url
                newFeedItem.sitelinkFinalUrls = New UrlList()
                newFeedItem.sitelinkFinalUrls.urls = feedItem.FinalUrls
                newFeedItem.sitelinkFinalMobileUrls = New UrlList()
                newFeedItem.sitelinkFinalMobileUrls.urls = feedItem.FinalMobileUrls
                newFeedItem.sitelinkTrackingUrlTemplate = feedItem.TrackingUrlTemplate
                newFeedItem.sitelinkLine2 = feedItem.Line2
                newFeedItem.sitelinkLine3 = feedItem.Line3

                extensionFeedItems.Add(newFeedItem)
            Next
            extensionSetting.extensionSetting.extensions = extensionFeedItems.ToArray()
            extensionSetting.extensionSetting.platformRestrictions = platformRestrictions
            extensionSetting.extensionType = FeedType.SITELINK

            Using campaignExtensionSettingService As CampaignExtensionSettingService =
                DirectCast(user.GetService(AdWordsService.v201809.CampaignExtensionSettingService),
                           CampaignExtensionSettingService)

                Dim operation As New CampaignExtensionSettingOperation()
                operation.operand = extensionSetting
                operation.operator = [Operator].ADD

                campaignExtensionSettingService.mutate(
                    New CampaignExtensionSettingOperation() {operation})

                Return
            End Using
        End Sub

        ''' <summary>
        ''' Deletes a campaign feed.
        ''' </summary>
        ''' <param name="user">The AdWords user.</param>
        ''' <param name="campaignFeed">The campaign feed.</param>
        ''' <returns></returns>
        Private Function DeleteCampaignFeed(ByVal user As AdWordsUser,
                                            ByVal campaignFeed As CampaignFeed) As CampaignFeed
            Using campaignFeedService As CampaignFeedService = DirectCast(
                user.GetService(
                    AdWordsService.v201809.CampaignFeedService),
                CampaignFeedService)

                Dim operation As New CampaignFeedOperation()
                operation.operand = campaignFeed
                operation.operator = [Operator].REMOVE

                Return campaignFeedService.mutate(New CampaignFeedOperation() {operation}).value(0)
            End Using
        End Function

        ''' <summary>
        ''' Gets the platform restrictions for sitelinks in a campaign.
        ''' </summary>
        ''' <param name="campaignFeed">The campaign feed.</param>
        ''' <returns>The platform restrictions.</returns>
        Private Function GetPlatformRestrictionsForCampaign(ByVal campaignFeed As CampaignFeed) As _
            ExtensionSettingPlatform
            Dim platformRestrictions As String = "NONE"

            If campaignFeed.matchingFunction.operator = FunctionOperator.AND Then

                For Each argument As FunctionArgumentOperand In _
                    campaignFeed.matchingFunction.lhsOperand
                    ' Check if matchingFunction is of the form EQUALS(CONTEXT.DEVICE, 'Mobile').
                    If TypeOf argument Is FunctionOperand Then
                        Dim operand As FunctionOperand = CType(argument, FunctionOperand)
                        If operand.value.operator = FunctionOperator.EQUALS Then
                            Dim requestContextOperand As RequestContextOperand =
                                    CType(operand.value.lhsOperand(0), RequestContextOperand)
                            If (Not requestContextOperand Is Nothing) AndAlso
                               (requestContextOperand.contextType =
                                RequestContextOperandContextType.DEVICE_PLATFORM) Then
                                platformRestrictions = DirectCast(operand.value.rhsOperand(0),
                                                                  ConstantOperand).stringValue
                            End If
                        End If
                    End If
                Next
            End If

            Return _
                CType([Enum].Parse(GetType(ExtensionSettingPlatform), platformRestrictions, True),
                      ExtensionSettingPlatform)
        End Function

        ''' <summary>
        ''' Gets the list of feed items that are used by a campaign through a given
        ''' campaign feed.
        ''' </summary>
        ''' <param name="campaignFeed">The campaign feed.</param>
        ''' <returns>The list of feed items.</returns>
        Private Function GetFeedItemsForCampaign(ByVal campaignFeed As CampaignFeed) _
            As List(Of Long)
            Dim feedItems As New List(Of Long)()

            Select Case campaignFeed.matchingFunction.operator
                Case FunctionOperator.IN
                    ' Check if matchingFunction is of the form IN(FEED_ITEM_ID,{xxx,xxx}).
                    ' Extract feedItems if applicable.
                    feedItems.AddRange(GetFeedItemsFromArgument(campaignFeed.matchingFunction))

                Case FunctionOperator.AND
                    ' Check each condition.

                    For Each argument As FunctionArgumentOperand In _
                        campaignFeed.matchingFunction.lhsOperand
                        ' Check if matchingFunction is of the form IN(FEED_ITEM_ID,{xxx,xxx}).
                        ' Extract feedItems if applicable.
                        If TypeOf argument Is FunctionOperand Then
                            Dim operand As FunctionOperand = CType(argument, FunctionOperand)
                            If operand.value.operator = FunctionOperator.IN Then
                                feedItems.AddRange(GetFeedItemsFromArgument(operand.value))
                            End If
                        End If
                    Next

                Case Else
                    ' There are no other matching functions involving feeditem ids.
            End Select

            Return feedItems
        End Function

        Private Function GetFeedItemsFromArgument(ByVal func As [Function]) As List(Of Long)
            Dim feedItems As New List(Of Long)()

            If func.lhsOperand.Length = 1 Then
                Dim requestContextOperand As RequestContextOperand =
                        CType(func.lhsOperand(0), RequestContextOperand)
                If Not (requestContextOperand Is Nothing) AndAlso
                   (requestContextOperand.contextType =
                    RequestContextOperandContextType.FEED_ITEM_ID) Then
                    For Each argument As ConstantOperand In func.rhsOperand
                        feedItems.Add(argument.longValue)
                    Next
                End If
            End If

            Return feedItems
        End Function

        ''' <summary>
        ''' Gets the campaignfeeds that use a particular feed.
        ''' </summary>
        ''' <param name="user">The user that owns the feed.</param>
        ''' <param name="feed">The feed for which campaign feeds should be
        ''' retrieved.</param>
        ''' <param name="placeholderType">The type of placeholder to restrict
        ''' search.</param>
        ''' <returns>The list of campaignfeeds.</returns>
        Private Function GetCampaignFeeds(ByVal user As AdWordsUser, ByVal feed As Feed,
                                          ByVal placeholderType As Integer) As CampaignFeed()
            Using campaignFeedService As CampaignFeedService = DirectCast(
                user.GetService(
                    AdWordsService.v201809.CampaignFeedService),
                CampaignFeedService)

                Dim page As CampaignFeedPage = campaignFeedService.query(
                    String.Format(
                        "SELECT CampaignId, MatchingFunction, PlaceholderTypes " &
                        "WHERE Status='ENABLED' " &
                        "AND FeedId = '{0}' AND PlaceholderTypes CONTAINS_ANY[{1}]", feed.id,
                        placeholderType))
                Return page.entries
            End Using
        End Function
    End Class
End Namespace