Verificar o status e os diagnósticos da solicitação

As solicitações para enviar eventos ou membros do público-alvo são processadas de forma assíncrona. Uma resposta de ingestão bem-sucedida retorna um request_id e indica que a solicitação atendeu a todos os requisitos e foi aceita para processamento. No entanto, ele não indica se os registros na solicitação foram processados com sucesso.

Use o request_id retornado com RetrieveRequestStatus para verificar o status do upload e analisar os diagnósticos.

Confira o fluxo de trabalho recomendado para verificar o status das suas solicitações e a integridade dos uploads de eventos e públicos-alvo:

1. Emita solicitações para enviar eventos ou enviar ou remover membros do público-alvo.

2. Verifique o status geral de cada solicitação de ingestão. Uma solicitação bem-sucedida tem um Status com code igual a 0 (valor de tipo enumerado OK, resposta HTTP 200 OK) e retorna um IngestEventsResponse, IngestAudienceMembersResponse ou RemoveAudienceMembersResponse.

   Se uma solicitação não for bem-sucedida, modifique-a para corrigir o erro e envie-a novamente.

   Se uma solicitação for bem-sucedida, capture o request_id da resposta para usá-lo para verificar o status do processamento na próxima etapa.

3. Aguarde 30 minutos e envie uma solicitação RetrieveRequestStatus para cada request_id bem-sucedido.

   Um RetrieveRequestStatusRequest requer um único valor request_id. Envie uma solicitação de status separada para cada ID de solicitação que você capturou de uma solicitação de ingestão bem-sucedida.

   Repita periodicamente essa etapa para cada request_id até que o status do destino de cada destino chegue a SUCCESS, PARTIAL_SUCCESS ou FAILED. Siga a estratégia de sondagem recomendada para aguardar entre cada solicitação.

4. Analise cada RetrieveRequestStatusResponse para confirmar se os uploads estão funcionando corretamente e identificar problemas com os dados.

5. Corrija problemas de dados.

6. Volte para a etapa 1 e repita até resolver todos os problemas com os uploads.

Verificar o status geral do destino

O request_status_per_destination em um RetrieveRequestStatusResponse contém uma entrada separada para cada destino na solicitação de ingestão correspondente.

Por exemplo, se o IngestAudienceMembersRequest contiver três entradas na lista destinations para enviar dados a três públicos-alvo diferentes, a resposta de status vai conter três entradas em request_status_per_destination (uma entrada por público-alvo).

Verifique o campo request_status em cada RequestStatusPerDestination para determinar se a API Data Manager terminou de processar os dados desse destino.

Estes são os valores possíveis de request_status:

• PROCESSING: os dados do destino ainda estão sendo processados. Os avisos e erros não são preenchidos para o destino nesta etapa. Continue a sondagem até que o status chegue a um estado terminal.

• SUCCESS: o processamento da solicitação para o destino foi concluído sem erros. Verifique se há avisos sinalizados durante o processamento.

• FAILED: todos os registros do destino falharam devido a erros. Verifique se há avisos e erros para determinar por que todos os registros falharam. Verifique também se há avisos sinalizados durante o processamento.

• PARTIAL_SUCCESS: alguns dos registros do destino foram bem-sucedidos, mas outros falharam devido a erros. Verifique se há erros para determinar por que alguns registros falharam. Verifique também se há avisos sinalizados durante o processamento.

Revisar diagnósticos

Quando o request_status de um destino atingir SUCCESS, FAILED ou PARTIAL_SUCCESS, revise os diagnósticos detalhados na resposta para verificar as contagens e resolver problemas.

Verificar o status do evento ou do público-alvo por destino

Inspecione o campo de status que corresponde ao tipo de solicitação de ingestão. Apenas um dos campos a seguir é definido em cada RequestStatusPerDestination:

• events_ingestion_status

• audience_members_ingestion_status

• audience_members_removal_status

Status de ingestão de eventos

O campo events_ingestion_status será preenchido se a solicitação for um IngestEventsRequest.

Verifique o record_count do IngestEventStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Status de ingestão de membros do público-alvo

O campo audience_members_ingestion_status será preenchido se a solicitação for um IngestAudienceMembersRequest. Este é o campo IngestAudienceMembersStatus para verificar cada tipo de dados de público-alvo. Apenas um desses campos é definido.

composite_data_ingestion_status

Verifique o record_count do IngestCompositeDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o data_type_counts para confirmar se o número de identificadores corresponde às suas expectativas. Essa lista detalha todos os identificadores recebidos (como endereço de e-mail, número de telefone, endereço físico e endereço IP) por DataType.

Se a solicitação tiver um número suficiente de registros, o upload_match_rate_range vai conter o intervalo de taxa de correspondência para os registros na solicitação.

google_user_id_data_ingestion_status

Verifique o record_count do IngestGoogleUserIdDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o google_user_id_count para confirmar se o número de IDs de usuário do Google recebidos corresponde às suas expectativas.

mobile_data_ingestion_status

Verifique o record_count do IngestMobileDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o mobile_id_count para confirmar se o número de IDs digitais recebidos corresponde às suas expectativas.

pair_data_ingestion_status

Verifique o record_count do IngestPairDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o pair_id_count para confirmar se o número de IDs de PAIR recebidos corresponde às suas expectativas.

partner_provided_id_data_ingestion_status

Verifique o record_count do IngestPartnerProvidedIdDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o partner_provided_id_count para confirmar se o número de IDs fornecidos pelo parceiro recebidos corresponde às suas expectativas.

ppid_data_ingestion_status

Verifique o record_count do IngestPpidDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o ppid_count para confirmar se o número de PPIDs recebidos corresponde às suas expectativas.

user_data_ingestion_status

Verifique o record_count do IngestUserDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o user_identifier_count para confirmar se o número de identificadores de usuário recebidos corresponde às suas expectativas.

Se a solicitação tiver um número suficiente de registros, o upload_match_rate_range vai conter o intervalo de taxa de correspondência para os registros na solicitação.

user_id_data_ingestion_status

Verifique o record_count do IngestUserIdDataStatus para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Verifique o user_id_count para confirmar se o número de IDs de usuário recebidos corresponde às suas expectativas.

Status de remoção de membros do público-alvo

O campo audience_members_removal_status será preenchido se a solicitação for um RemoveAudienceMembersRequest. Confira o campo RemoveAudienceMembersStatus para verificar cada tipo de dados de público-alvo. Apenas um desses campos é definido.

composite_data_removal_status

Status de remoção de dados compostos

google_user_id_data_removal_status

Status de remoção dos dados do ID do usuário do Google

mobile_data_removal_status

Status de remoção de dados móveis.

pair_data_removal_status

Status de remoção dos dados da PAIR.

partner_provided_id_data_removal_status

Status de remoção dos dados de ID fornecidos pelo parceiro

ppid_data_removal_status

Status de remoção dos dados do PPID.

user_data_removal_status

Status de remoção dos dados do usuário.

user_id_data_removal_status

Status de remoção dos dados do ID do usuário

Verifique o record_count para confirmar se o número total de registros recebidos corresponde às suas expectativas. O record_count inclui registros bem-sucedidos e com falha.

Além disso, verifique user_identifier_count, mobile_id_count, pair_id_count, ppid_count, user_id_count, google_user_id_count ou partner_provided_id_count para confirmar a contagem total de identificadores recebidos.

Para dados compostos, verifique o data_type_counts para confirmar se o número de identificadores corresponde às suas expectativas. Essa lista detalha todos os identificadores recebidos (como endereço de e-mail, número de telefone, endereço físico e endereço IP) pelo DataType.

Verificar avisos e erros

Além dos campos de status para o destino e o tipo de solicitação, o RetrieveRequestStatusResponse contém um detalhamento de avisos e erros para a solicitação.

• Um erro indica que a API rejeitou completamente o registro.

• Um aviso indica que a API não rejeitou o registro, mas teve que ignorar partes dos dados do registro.

Por exemplo, se um Event contiver dados criptografados de UserIdentifier e AdIdentifiers, como gclid, e os dados de UserIdentifier não puderem ser descriptografados, a API Data Manager ainda vai processar o registro usando o AdIdentifiers, mas vai retornar o aviso PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR.

No entanto, se o Event não contiver AdIdentifiers e os dados de UserIdentifier não puderem ser descriptografados, a API Data Manager vai rejeitar todo o registro e informar o erro PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR, porque um Event válido precisa ter pelo menos um de ad_identifiers ou user_data.

Estes são os campos de resposta que contêm informações de aviso e erro. Esses campos são preenchidos quando o status geral do destino atinge SUCCESS, PARTIAL_SUCCESS ou FAILED.

warning_info

Um objeto WarningInfo. O campo warning_counts contém uma lista de objetos WarningCount. Cada WarningCount contém:

• reason: o tipo de aviso.

• record_count: o número de registros que tiveram esse tipo de aviso.

• record_indices: os índices dos registros na solicitação original que tinham esse tipo de aviso. Consulte Verificar registros afetados.

Verifique o warning_info mesmo que o status geral do destino seja SUCCESS.

error_info

Um objeto ErrorInfo. O campo error_counts contém uma lista de objetos ErrorCount. Cada ErrorCount contém:

• reason: o tipo de erro.

• record_count: o número de registros que falharam devido a esse tipo de erro.

• record_indices: os índices dos registros na solicitação original que falharam devido a esse tipo de erro. Consulte Verificar registros afetados.

Verificar registros afetados

Use o record_indices de cada WarningCount e ErrorCount para identificar os registros exatos na solicitação de ingestão que tiveram avisos ou erros.

Cada valor em record_indices é a posição baseada em 0 de um registro na solicitação original:

• Para um IngestEventsRequest, o índice se refere à posição do evento na lista events da solicitação.

• Para um IngestAudienceMembersRequest, o índice se refere à posição do membro do público-alvo na lista audience_members da solicitação.

Por exemplo, um valor record_indices de 0 se refere ao primeiro evento ou membro do público-alvo na solicitação.

Lembre-se do seguinte ao analisar record_indices:

• Os índices são informados por destino. Se a solicitação tiver vários destinos, cada RequestStatusPerDestination vai informar os índices dos registros com avisos ou erros para esse destino. O mesmo registro pode aparecer em mais de um RequestStatusPerDestination.

• Um registro pode aparecer em mais de um motivo. Por exemplo, um registro pode ter um erro e um aviso ou mais de um tipo de aviso. Para encontrar todos os problemas de um determinado registro, verifique cada WarningCount e ErrorCount do destino.

Veja um exemplo de RetrieveRequestStatusResponse para um IngestEventsRequest com cinco eventos e um destino. O primeiro evento (índice 0) e o quarto evento (índice 3) falharam porque o ID da transação já havia sido enviado, e o terceiro evento (índice 2) foi processado, mas tinha um valor de variável personalizada que não é predefinido.

{
  "requestStatusPerDestination": [
    {
      "destination": {
        "operatingAccount": {
          "accountType": "GOOGLE_ADS",
          "accountId": "1234567890"
        },
        "productDestinationId": "123456789"
      },
      "requestStatus": "PARTIAL_SUCCESS",
      "eventsIngestionStatus": {
        "recordCount": "5"
      },
      "errorInfo": {
        "errorCounts": [
          {
            "recordCount": "2",
            "reason": "PROCESSING_ERROR_REASON_DUPLICATE_TRANSACTION_ID",
            "recordIndices": [0, 3]
          }
        ]
      },
      "warningInfo": {
        "warningCounts": [
          {
            "recordCount": "1",
            "reason": "PROCESSING_WARNING_REASON_CUSTOM_VARIABLE_NOT_PREDEFINED",
            "recordIndices": [2]
          }
        ]
      }
    }
  ]
}

Para corrigir os registros:

1. Para cada ErrorCount e WarningCount, use o record_indices para procurar os registros correspondentes na solicitação original.

2. Use o reason para determinar como corrigir cada registro. Para descrições de cada motivo, consulte ProcessingErrorReason e ProcessingWarningReason.

3. Envie uma nova solicitação de ingestão que contenha apenas os registros corrigidos. Não reenvie registros que foram bem-sucedidos, porque isso pode resultar em dados duplicados ou erros adicionais.

Estratégia de sondagem

Envie periodicamente o RetrieveRequestStatusRequest usando um algoritmo de espera exponencial até que o request_status alcance SUCCESS, FAILED ou PARTIAL_SUCCESS para cada destino na solicitação original. Isso pode levar até 24 horas, embora a API Data Manager possa concluir o processamento de algumas solicitações em apenas 30 minutos.

Veja um exemplo de uma configuração razoável de tempo de espera inicial e nova tentativa que equilibra a atividade e o uso da cota:

Confira uma sequência de solicitações e o tempo decorrido com essa configuração:

Adicione uma pequena quantidade aleatória de jitter aos atrasos de espera para evitar o problema de "rebanho estrondoso", em que muitos clientes tentam novamente ao mesmo tempo.

Requisitos de autorização

Um RetrieveRequestStatusRequest não aceita contas de destino ou cabeçalhos da solicitação. Em vez disso, a API Data Manager identifica os destinos da solicitação de ingestão original associada ao request_id e verifica se o autor da chamada tem acesso ao operating_account em cada Destination.

Para verificar o status de uma solicitação, as credenciais usadas em um RetrieveRequestStatusRequest precisam atender aos seguintes requisitos para o operating_account de cada destino da solicitação de ingestão original:

• Caminho de acesso idêntico: as credenciais precisam ter acesso a cada operating_account usando o mesmo caminho de acesso especificado na solicitação de ingestão original.

  Por exemplo, se uma solicitação de ingestão para um operating_account do Google Ads especificou uma conta de administrador principal como login_account, as credenciais também precisam ter acesso ao operating_account por meio dessa mesma conta de administrador. Mesmo que a Conta do Google associada às credenciais tenha acesso direto ao operating_account secundário, a solicitação vai falhar com um erro PERMISSION_DENIED se essa conta não tiver acesso pela conta de administrador do login_account especificada durante a ingestão.

• Nível de acesso suficiente: a Conta do Google associada às credenciais precisa ter um nível de acesso ou uma função com permissão para ingerir dados no operating_account.

  Por exemplo, no Google Ads, a Conta do Google precisa ter o nível de acesso Administrador ou Padrão. Uma solicitação com credenciais para uma conta com o nível de acesso Somente leitura falha com um erro PERMISSION_DENIED.