Acceso de cuenta única

Si desea acceder a una sola cuenta de usuario, todo comienza con el objeto AdsApp .

¿Cómo puedo acceder a las entidades de mi cuenta?

Se usa AdsApp para acceder a todas las entidades de la cuenta. El objeto contiene un método selector para cada tipo de entidad (por ejemplo, campañas, grupos de anuncios y palabras clave). El método selector devuelve todas las entidades de ese tipo de entidad. Por ejemplo, para obtener todos los grupos de anuncios de la cuenta, llame adGroups() al método.

    var iterator = AdsApp.adGroups().get();

Pero, ¿qué sucede si quiero una entidad específica o un subconjunto de entidades?

El selector ofrece diferentes maneras de filtrar la lista de entidades. Puede usar el método del withIds() selector para obtener entidades específicas por identificadores o puede usarlo withCondition() para especificar los criterios de selección para seleccionar las entidades. Los selectores para todos los tipos de entidad, excepto para las listas de palabras clave negativas, permiten filtrar la lista de entidades.

Use la notación de puntos para encadenar varios filtros. Si especifica varios filtros, se tratan como una operación AND: el selector devuelve solo las entidades que coinciden con todas las condiciones.

Para obtener todos los grupos de anuncios de una campaña, usa el withCondition() método para especificar el nombre de la campaña.

    var campaignName = 'My Campaign';
    var iterator = AdsApp.adGroups()
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

Para obtener una lista de condiciones y operadores que puede utilizar para filtrar la lista de entidades, vea el método del withCondition() selector. Por ejemplo, para obtener una lista de condiciones de grupo de anuncios, consulta el método withCondition del selector de grupos de anuncios.

Para obtener un grupo de anuncios por identificador, usa el withIds() método para especificar el grupo de anuncios que se va a obtener.

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

O bien, puedes obtener el grupo de anuncios por el nombre.

    var campaignName = 'My Campaign';
    var adGroupName = 'My AdGroup';
    var iterator = AdsApp.adGroups()
        .withCondition(`CampaignName = '${campaignName}'`)
        .withCondition(`Name = '${adGroupName}'`)
        .get();

Para obtener más información sobre los selectores, consulte ¿Qué son los selectores?

¿Cómo puedo usar el selector para iterar por la lista filtrada de entidades?

No lo haces. El selector solo define las entidades que desea obtener. Para obtener realmente las entidades, usa un iterador. Para obtener el iterador, se llama al método del get() selector.

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

Usa un bucle while simple para iterar sobre la lista de entidades.

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        
        // Do something with the entity
    }

Para obtener más información sobre los iteradores, consulte ¿Qué son los iteradores?

Cómo obtengo los datos de rendimiento de una entidad?

La mayoría de las entidades le permiten solicitar datos de rendimiento, si están disponibles. Pero primero debe indicar a Scripts el intervalo de fechas de los datos de rendimiento al especificar el selector. Para especificar un intervalo de fechas, use un literal predefinido, como AYER o LAST_MONTH, o use una fecha de inicio y finalización. Para obtener más información, vea forDateRange(string dateRange) y forDateRange(Object dateFrom, Object dateTo).

    var campaignName = 'My Campaign';
    var adGroupName = 'My AdGroup';
    var iterator = AdsApp.adGroups()
        .forDateRange('LAST_30_DAYS')
        .withCondition(`CampaignName = '${campaignName}'`)
        .withCondition(`Name = '${adGroupName}'`)
        .get();

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        var stats = adGroup.getStats();
    }

También debe especificar un intervalo de fechas si especifica una columna de datos de rendimiento en el método de withCondition() un selector. Por ejemplo, si quieres solo grupos de anuncios que tengan una CTR superior al 0,22 %, deberás especificar un intervalo de fechas.

    var startDate = {year: 2018, month: 6, day: 3};
    var endDate = {year: 2018, month: 6, day: 13};

    var iterator = AdsApp.adGroups()
        .forDateRange(startDate, endDate)
        .withCondition("Ctr > 0.22")
        .get();

Cómo agrego una entidad?

Para agregar una entidad, utilice un objeto builder. Para obtener un objeto de generador, llame al método new* en el objeto principal al que va a agregar hijos. Por ejemplo, para agregar grupos de anuncios a una campaña, llama al método de newAdGroupBuilder() la campaña.

El objeto builder contiene métodos para establecer todas las propiedades del objeto que puede especificar. También incluye un build() método que puede utilizar para crear la entidad. A continuación se muestra cómo crear un grupo de anuncios. (Para obtener información acerca de cómo obtener un objeto de campaña, vea Obtener una campaña por nombre).

        var adGroupName = "My ad group";
        var endDate = {year: 2018, month: 6, day: 13};
        var customParameters = {key1: 'value1', key2: 'value2', key3: 'value3'};

        var adGroupOperation = campaign.newAdGroupBuilder()
            .withName(adGroupName)
            .withStatus('ENABLED')
            .withLanguage('English')
            .withBiddingStrategy('MANUAL_CPC')
            .withCpc(1.2)
            .withCustomParameters(customParameters)
            .withEndDate(endDate)
            .build();

El build método devuelve un objeto de operación, que puede usar para comprobar si Scripts creó correctamente la entidad. A continuación se muestra el patrón de llamada típico. Llame al getResult método solo si desea tener acceso a las propiedades de la nueva entidad.

    if (adGroupOperation.isSuccessful()) {
        var adGroup = adGroupOperation.getResult();

    }
    else {
        for (var error of adGroupOperation.getErrors()) {
            Logger.log(`${error}\n`);
        }
    }

Para obtener más información sobre los generadores y las consideraciones de rendimiento al llamar a los métodos de operación, consulte ¿Qué son los constructores?

Cómo actualizo una entidad?

Después de usar un objeto builder para agregar una entidad, usa los métodos de la entidad para actualizar sus propiedades. En el ejemplo siguiente se actualiza el importe de la puja de CPC del grupo de anuncios.

    var ids = ["123456789"];
    var adGroups = AdsApp.adGroups()
        .withIds(ids)
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        adGroup.bidding().setCpc(2.5);
    }

Pero, ¿cómo puedo saber si la actualización ha funcionado?

Si intenta actualizar una propiedad con un valor no válido, Scripts escribe un error en el registro de cambios, pero no produce una excepción, por lo que el script continúa ejecutándose. No obtenga la propiedad después de actualizarla para comprobar si contiene el nuevo valor; Esto afecta negativamente al rendimiento.

function main() {
    var id = "123456789";
    var bidAmount = -2.5;  
    var keyword = getKeyword(id); 

    if (keyword != null) {
        keyword.bidding().setCpc(bidAmount);  // Bid is not set because bid amount is not valid
    }

}

function getKeyword(id) {
    var keywords = AdsApp.keywords()
        .withIds([id])
        .get();

    if (keywords.hasNext()) {
        return keywords.next();
    }
    else {
        return null;
    }    
}

Escritura en el archivo de registro

Scripts proporciona un archivo de registro en el que puede escribir información de seguimiento y depuración. Para obtener información, consulte Registros de cambios y registros de texto.

Pasos siguientes

Introducción