A API Search Ads 360 Reporting anterior será desativada em 30 de junho de 2024. A API Search Ads 360 Conversion não foi afetada e vai continuar compatível. Todo novo desenvolvimento de relatórios precisa usar a nova API Search Ads 360 Reporting.

A partir de abril de 2024, um erro supportedApiVersion será retornado ao solicitar um relatório. Veja os detalhes aqui.

Também é altamente recomendável migrar as implementações atuais do Search Ads 360 para a nova API. Consulte o Guia de introdução e o Guia de migração da nova API Search Ads 360 Reporting para saber mais informações.

Esta página foi traduzida pela API Cloud Translation.

Reports

Para ver uma lista de métodos desse recurso, consulte o final desta página.

Representações de recursos

Um relatório do DoubleClick Search. Esse objeto contém a solicitação do relatório, alguns metadados do relatório, como o código da moeda, e as linhas ou os arquivos do relatório gerados.

{
  "kind": "doubleclicksearch#report",
  "id": string,
  "isReportReady": boolean,
  "request": {
    "reportScope": {
      "agencyId": long,
      "advertiserId": long,
      "engineAccountId": long,
      "campaignId": long,
      "adGroupId": long,
      "keywordId": long,
      "adId": long
    },
    "reportType": string,
    "columns": [
      {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      }
    ],
    "timeRange": {
      "startDate": string,
      "endDate": string,
      "changedMetricsSinceTimestamp": datetime,
      "changedAttributesSinceTimestamp": datetime
    },
    "filters": [
      {
        "column": {
          "columnName": string,
          "savedColumnName": string,
          "customDimensionName": string,
          "customMetricName": string,
          "headerText": string,
          "startDate": string,
          "endDate": string,
          "groupByColumn": boolean,
          "platformSource": string,
          "productReportPerspective": string
        },
        "operator": string,
        "values": [
          (value)
        ]
      }
    ],
    "orderBy": [
      {
        "column": {
          "columnName": string,
          "savedColumnName": string,
          "customDimensionName": string,
          "customMetricName": string,
          "headerText": string,
          "startDate": string,
          "endDate": string,
          "groupByColumn": boolean,
          "platformSource": string,
          "productReportPerspective": string
        },
        "sortOrder": string
      }
    ],
    "includeDeletedEntities": boolean,
    "includeRemovedEntities": boolean,
    "verifySingleTimeZone": boolean,
    "downloadFormat": string,
    "statisticsCurrency": string,
    "startRow": integer,
    "rowCount": integer,
    "maxRowsPerFile": integer
  },
  "statisticsCurrencyCode": string,
  "statisticsTimeZone": string,
  "rowCount": integer,
  "files": [
    {
      "url": string,
      "byteCount": long
    }
  ],
  "rows": [
    {
      (key): (value)
    }
  ]
}

Nome da propriedade	Valor	Descrição
`files[]`	`list`	Apenas para relatórios assíncronos. Contém uma lista dos arquivos de relatório gerados quando o relatório é concluído.
`files[].byteCount`	`long`	O tamanho deste arquivo de relatório em bytes.
`files[].url`	`string`	Use esse URL para fazer o download do arquivo de relatório.
`id`	`string`	Apenas para relatórios assíncronos. ID do relatório.
`isReportReady`	`boolean`	Apenas para relatórios assíncronos. Verdadeiro se e somente se o relatório tiver sido concluído e os arquivos estiverem prontos para download.
`kind`	`string`	Identifica como um recurso de relatório. Valor: a string fixa `doubleclicksearch#report`.
`request`	`nested object`	A solicitação que criou o relatório. Os campos opcionais não especificados na solicitação original são preenchidos com valores padrão.
`request.columns[]`	`list`	As colunas a serem incluídas no relatório. Isso inclui colunas do DoubleClick Search e colunas salvas. Para colunas do DoubleClick Search, somente o parâmetro `columnName` é obrigatório. Para colunas salvas, apenas o parâmetro `savedColumnName` é obrigatório. Tanto `columnName` quanto `savedColumnName` não podem ser definidos na mesma estrofe. O número máximo de colunas por solicitação é 300.
`request.columns[].columnName`	`string`	Nome de uma coluna do DoubleClick Search para incluir no relatório.
`request.columns[].customDimensionName`	`string`	Segmenta um relatório por uma dimensão personalizada. É necessário definir o escopo do relatório para um anunciante ou menos, e a dimensão personalizada já precisa estar configurada no DoubleClick Search. O nome da dimensão personalizada, que aparece no DoubleClick Search, diferencia maiúsculas de minúsculas. Se usada em um relatório de conversão, retorna o valor da dimensão personalizada especificada para a conversão especificada, se definido. Esta coluna não segmenta o relatório de conversão.
`request.columns[].customMetricName`	`string`	Nome de uma métrica personalizada a ser incluída no relatório. É necessário definir o escopo do relatório para um anunciante ou um nível inferior, e a métrica personalizada já precisa estar configurada no DoubleClick Search. O nome da métrica personalizada, que aparece no DoubleClick Search, diferencia maiúsculas de minúsculas.
`request.columns[].endDate`	`string`	Dia inclusivo no formato AAAA-MM-DD. Quando fornecidas, elas substituem o período geral do relatório somente para essa coluna. Precisa ser fornecido com `startDate`.
`request.columns[].groupByColumn`	`boolean`	Apenas relatório síncrono. Defina como `true` para agrupar por essa coluna. O padrão é `false`.
`request.columns[].headerText`	`string`	Texto usado para identificar essa coluna na saída do relatório. Quando não especificado, o padrão é `columnName` ou `savedColumnName`. Isso pode ser usado para evitar colisões entre colunas do DoubleClick Search e colunas salvas com o mesmo nome.
`request.columns[].platformSource`	`string`	A plataforma usada para fornecer dados para a dimensão personalizada. Os valores aceitáveis são "Floodlight".
`request.columns[].productReportPerspective`	`string`	Retorna métricas apenas para um tipo específico de atividade de produto. Os valores aceitos são: "`sold`": retorna métricas apenas para produtos que foram vendidos "`advertised`": retorna métricas apenas para produtos que foram anunciados em uma campanha do Shopping e que podem ou não ter sido vendidos.
`request.columns[].savedColumnName`	`string`	Nome de uma coluna salva a ser incluída no relatório. O relatório precisa ter o escopo definido para o anunciante ou menos, e essa coluna salva já precisa ter sido criada na IU do DoubleClick Search.
`request.columns[].startDate`	`string`	Data inclusiva no formato AAAA-MM-DD. Quando fornecidas, elas substituem o período geral do relatório somente para essa coluna. Precisa ser fornecido com `endDate`.
`request.downloadFormat`	`string`	Formato em que o relatório será retornado. Atualmente, há suporte para `csv` ou `tsv`.
`request.filters[]`	`list`	Uma lista de filtros a serem aplicados ao relatório. O número máximo de filtros por solicitação é 300.
`request.filters[].column`	`nested object`	Coluna para executar o filtro. Pode ser uma coluna do DoubleClick Search ou uma coluna salva.
`request.filters[].column.columnName`	`string`	Nome de uma coluna do DoubleClick Search para incluir no relatório.
`request.filters[].column.customDimensionName`	`string`	Segmenta um relatório por uma dimensão personalizada. É necessário definir o escopo do relatório para um anunciante ou menos, e a dimensão personalizada já precisa estar configurada no DoubleClick Search. O nome da dimensão personalizada, que aparece no DoubleClick Search, diferencia maiúsculas de minúsculas. Se usada em um relatório de conversão, retorna o valor da dimensão personalizada especificada para a conversão especificada, se definido. Esta coluna não segmenta o relatório de conversão.
`request.filters[].column.customMetricName`	`string`	Nome de uma métrica personalizada a ser incluída no relatório. É necessário definir o escopo do relatório para um anunciante ou um nível inferior, e a métrica personalizada já precisa estar configurada no DoubleClick Search. O nome da métrica personalizada, que aparece no DoubleClick Search, diferencia maiúsculas de minúsculas.
`request.filters[].column.endDate`	`string`	Dia inclusivo no formato AAAA-MM-DD. Quando fornecidas, elas substituem o período geral do relatório somente para essa coluna. Precisa ser fornecido com `startDate`.
`request.filters[].column.groupByColumn`	`boolean`	Apenas relatório síncrono. Defina como `true` para agrupar por essa coluna. O padrão é `false`.
`request.filters[].column.headerText`	`string`	Texto usado para identificar essa coluna na saída do relatório. Quando não especificado, o padrão é `columnName` ou `savedColumnName`. Isso pode ser usado para evitar colisões entre colunas do DoubleClick Search e colunas salvas com o mesmo nome.
`request.filters[].column.platformSource`	`string`	A plataforma usada para fornecer dados para a dimensão personalizada. Os valores aceitáveis são "Floodlight".
`request.filters[].column.productReportPerspective`	`string`	Retorna métricas apenas para um tipo específico de atividade de produto. Os valores aceitos são: "`sold`": retorna métricas apenas para produtos que foram vendidos "`advertised`": retorna métricas apenas para produtos que foram anunciados em uma campanha do Shopping e que podem ou não ter sido vendidos.
`request.filters[].column.savedColumnName`	`string`	Nome de uma coluna salva a ser incluída no relatório. O relatório precisa ter o escopo definido para o anunciante ou menos, e essa coluna salva já precisa ter sido criada na IU do DoubleClick Search.
`request.filters[].column.startDate`	`string`	Data inclusiva no formato AAAA-MM-DD. Quando fornecidas, elas substituem o período geral do relatório somente para essa coluna. Precisa ser fornecido com `endDate`.
`request.filters[].operator`	`string`	Operador a ser usado no filtro. Consulte a referência de filtro para ver uma lista de operadores disponíveis.
`request.filters[].values[]`	`list`	Uma lista de valores para filtrar o valor da coluna. O número máximo de valores de filtro por solicitação é 300.
`request.includeDeletedEntities`	`boolean`	Determina se as entidades removidas devem ser incluídas no relatório. O valor padrão é `false`. Obsoleto. Use `includeRemovedEntities`.
`request.includeRemovedEntities`	`boolean`	Determina se as entidades removidas devem ser incluídas no relatório. O valor padrão é `false`.
`request.maxRowsPerFile`	`integer`	Apenas para relatórios assíncronos. O número máximo de linhas por arquivo de relatório. Um relatório grande é dividido em vários arquivos com base nesse campo. Os valores aceitáveis são de `1000000` a `100000000`, inclusive.
`request.orderBy[]`	`list`	Apenas relatório síncrono. Uma lista de colunas e rotas que definem a classificação a ser realizada nas linhas do relatório. O número máximo de pedidos por solicitação é 300.
`request.orderBy[].column`	`nested object`	Coluna para realizar a classificação. Ela pode ser uma coluna definida pelo DoubleClick Search ou uma coluna salva.
`request.orderBy[].column.columnName`	`string`	Nome de uma coluna do DoubleClick Search para incluir no relatório.
`request.orderBy[].column.customDimensionName`	`string`	Segmenta um relatório por uma dimensão personalizada. É necessário definir o escopo do relatório para um anunciante ou menos, e a dimensão personalizada já precisa estar configurada no DoubleClick Search. O nome da dimensão personalizada, que aparece no DoubleClick Search, diferencia maiúsculas de minúsculas. Se usada em um relatório de conversão, retorna o valor da dimensão personalizada especificada para a conversão especificada, se definido. Esta coluna não segmenta o relatório de conversão.
`request.orderBy[].column.customMetricName`	`string`	Nome de uma métrica personalizada a ser incluída no relatório. É necessário definir o escopo do relatório para um anunciante ou um nível inferior, e a métrica personalizada já precisa estar configurada no DoubleClick Search. O nome da métrica personalizada, que aparece no DoubleClick Search, diferencia maiúsculas de minúsculas.
`request.orderBy[].column.endDate`	`string`	Dia inclusivo no formato AAAA-MM-DD. Quando fornecidas, elas substituem o período geral do relatório somente para essa coluna. Precisa ser fornecido com `startDate`.
`request.orderBy[].column.groupByColumn`	`boolean`	Apenas relatório síncrono. Defina como `true` para agrupar por essa coluna. O padrão é `false`.
`request.orderBy[].column.headerText`	`string`	Texto usado para identificar essa coluna na saída do relatório. Quando não especificado, o padrão é `columnName` ou `savedColumnName`. Isso pode ser usado para evitar colisões entre colunas do DoubleClick Search e colunas salvas com o mesmo nome.
`request.orderBy[].column.platformSource`	`string`	A plataforma usada para fornecer dados para a dimensão personalizada. Os valores aceitáveis são "Floodlight".
`request.orderBy[].column.productReportPerspective`	`string`	Retorna métricas apenas para um tipo específico de atividade de produto. Os valores aceitos são: "`sold`": retorna métricas apenas para produtos que foram vendidos "`advertised`": retorna métricas apenas para produtos que foram anunciados em uma campanha do Shopping e que podem ou não ter sido vendidos.
`request.orderBy[].column.savedColumnName`	`string`	Nome de uma coluna salva a ser incluída no relatório. O relatório precisa ter o escopo definido para o anunciante ou menos, e essa coluna salva já precisa ter sido criada na IU do DoubleClick Search.
`request.orderBy[].column.startDate`	`string`	Data inclusiva no formato AAAA-MM-DD. Quando fornecidas, elas substituem o período geral do relatório somente para essa coluna. Precisa ser fornecido com `endDate`.
`request.orderBy[].sortOrder`	`string`	A direção da classificação, que é `ascending` ou `descending`.
`request.reportScope`	`object`	O reportScope é um conjunto de IDs usados para determinar qual subconjunto de entidades será retornado no relatório. A linhagem completa de IDs do menor nível com escopo desejado pela agência é obrigatória.
`request.reportScope.adGroupId`	`long`	ID do grupo de anúncios do DS.
`request.reportScope.adId`	`long`	ID do anúncio do DS.
`request.reportScope.advertiserId`	`long`	ID do anunciante do DS.
`request.reportScope.agencyId`	`long`	ID da agência do DS.
`request.reportScope.campaignId`	`long`	ID da campanha do DS.
`request.reportScope.engineAccountId`	`long`	ID da conta de mecanismo do DS.
`request.reportScope.keywordId`	`long`	ID de palavra-chave do DS
`request.reportType`	`string`	Determina o tipo de linhas que são retornadas no relatório. Por exemplo, se você especificar `reportType: keyword`, cada linha do relatório terá dados sobre uma palavra-chave. Consulte a referência Tipos de relatórios para ver as colunas disponíveis para cada tipo.
`request.rowCount`	`integer`	Apenas relatório síncrono. O número máximo de linhas a serem retornadas. Outras linhas são descartadas. Os valores aceitáveis são de `0` a `10000`, inclusive. O valor padrão é `10000`.
`request.startRow`	`integer`	Apenas relatório síncrono. Índice baseado em zero da primeira linha a ser retornada. Os valores aceitáveis são de `0` a `50000`, inclusive. O valor padrão é `0`.
`request.statisticsCurrency`	`string`	Especifica a moeda em que o dinheiro será retornado. Os valores possíveis são: `usd`, `agency` (válido se o relatório estiver no escopo da agência ou inferior), `advertiser` (válido se o relatório estiver no escopo de * anunciante ou mais baixo) ou `account` (válido se o relatório estiver no escopo da conta de mecanismo ou inferior).
`request.timeRange`	`object`	Se as métricas forem solicitadas em um relatório, esse argumento será usado para restringir as métricas a um período específico.
`request.timeRange.changedAttributesSinceTimestamp`	`datetime`	Carimbo de data/hora inclusivo de UTC no formato RFC, por exemplo, `2013-07-16T10:16:23.555Z`. Veja referências adicionais sobre como funcionam os relatórios de atributos alterados.
`request.timeRange.changedMetricsSinceTimestamp`	`datetime`	Carimbo de data/hora inclusivo de UTC no formato RFC, por exemplo, `2013-07-16T10:16:23.555Z`. Veja mais referências sobre como os relatórios de métricas alteradas funcionam.
`request.timeRange.endDate`	`string`	Data inclusiva no formato AAAA-MM-DD.
`request.timeRange.startDate`	`string`	Data inclusiva no formato AAAA-MM-DD.
`request.verifySingleTimeZone`	`boolean`	Se for `true`, o relatório só será criado se todos os dados de estatísticas solicitados forem provenientes de um único fuso horário. O padrão é `false`.
`rowCount`	`integer`	O número de linhas de relatório geradas pelo relatório, sem incluir cabeçalhos.
`rows[]`	`list`	Apenas relatório síncrono. Linhas de relatório geradas.
`rows[].(key)`	`any value`	Indica as colunas que são representadas nesta linha. Ou seja, cada chave corresponde a uma coluna com uma célula não vazia nessa linha.
`statisticsCurrencyCode`	`string`	O código da moeda de todos os valores monetários produzidos no relatório, incluindo valores definidos por usuários (por exemplo, configurações de lance de palavra-chave) e métricas (por exemplo, custo e receita). O código da moeda de um relatório é determinado pelo campo `statisticsCurrency` da solicitação.
`statisticsTimeZone`	`string`	Se todas as estatísticas do relatório forem provenientes do mesmo fuso horário, isso será feito dessa forma. Caso contrário, o campo não será definido.

Métodos

gerar: Gera e retorna um relatório imediatamente.
get: Enquetes sobre o status de uma solicitação de relatório.
getFile (em inglês): Faz o download de um arquivo de relatório codificado em UTF-8.
getIdMappingFile (em inglês): Faz o download de um arquivo CSV (codificado em UTF-8) com mapeamentos de ID entre o Search Ads 360 antigo e o novo Search Ads 360. Para o anunciante solicitado, o arquivo inclui todas as entidades filhas (por exemplo, contas de mecanismo, campanhas, grupos de anúncios etc.) que estão no Search Ads 360 antigo e no novo Search Ads 360.
solicitação: Insere uma solicitação de relatório no sistema de relatórios.