Filtrar respostas da lista

A maioria dos serviços no Display & A API Video 360 fornece um método LIST para a recuperação em massa de do Google Cloud. Esses métodos LIST geralmente oferecem suporte à filtragem de resultados por uma parâmetro de consulta filter. Use este parâmetro para otimizar o uso da API apenas por para encontrar o que precisa.

Este guia mostra como usar o parâmetro filter de maneira eficaz.

Estrutura do filtro

Um valor de parâmetro filter é uma string que consiste em uma ou mais restrições que pode ser combinado com os operadores AND ou OR e agrupado usando parênteses.

As restrições têm o formato {field} {operator} {value}. Veja um exemplo:

entityStatus="ENTITY_STATUS_ACTIVE"

A string de filtro não pode exceder 500 caracteres. Se a string de filtro exceder 500 caracteres, siga um destes procedimentos:

• Divida a lógica em várias strings de filtro e recupere os recursos usando solicitações LIST separadas.
• Remova parte da lógica da string de filtro e use-a para filtrar o recursos recuperados localmente.

Coloque os valores de restrição entre aspas para garantir que a lógica seja aplicada corretamente.

Codifique as strings de filtro em URL ao fazer chamadas LIST diretamente sem usando uma biblioteca de cliente.

Consulte Lógica entre restrições para mais detalhes sobre formatação suas consultas.

Campos que aceitam filtros

Os campos filtráveis do método LIST são listados no filter do método. descrição do parâmetro. Na maioria dos casos, é possível filtrar um subconjunto da classe campos padrão. Em alguns casos raros, há campos adicionais que você pode usar apenas para filtragem.

Cada campo na descrição do parâmetro é compatível com pelo menos um dos seguintes operadores comparáveis:

Operadores comparáveis
EQUALS (=)	O valor do campo de recurso é igual ao valor informado. Exemplo: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=)	O valor do campo de recurso é menor ou igual ao valor informado. Usados com frequência ao comparar uma data ou data e hora. Exemplo: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)	O valor do campo de recurso é maior ou igual ao valor informado. Usados com frequência ao comparar uma data ou data e hora. Exemplo: updateTime>="2023-03-01T12:00:00Z"
HAS (:)	O valor do campo "resource" contém o valor informado. Se o campo "resource" for um ela verificará se o valor fornecido é uma substring existente. Se o o campo "resource" for uma matriz, ele verificará se a matriz contém as . Exemplo: lineItemIds:"1234"

Se nenhum operador for especificado para o campo na descrição do parâmetro, você só podem usar o operador EQUALS (=). Alguns campos aceitam vários operadores.

Alguns campos filtráveis, como os de datas e horas, exigem o um valor comparável de modo que sigam um formato específico. O formato é especificado ao lado de o campo na descrição do parâmetro filter.

Lógica entre restrições

É possível combinar várias restrições para restringir ou expandir a resposta das LIST.

Geralmente, é possível combinar várias restrições com AND e OR operadores lógicos. Cada método LIST especifica os operadores compatíveis. Alguns métodos aceitam apenas o uso de uma única restrição no parâmetro filter.

Considere as seguintes restrições ao criar strings de filtro com AND ou OR:

Observação: os exemplos a seguir foram escritos usando a filter do método advertisers.lineItems.list restrições de parâmetros.

• O AND precisa ser usado entre restrições ou grupos de restrições que filtrar campos diferentes ou que filtram o mesmo campo de maneira diferente. Aqui estão alguns exemplos:
  • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
  • updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
• OR precisa ser usado entre restrições individuais que filtram pelo mesmo . Aqui está um exemplo:
  • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

• Não é possível usar OR para combinar dois grupos de restrições. Usar várias Solicitações LIST com valores de filtro diferentes. Por exemplo, use o método seguintes solicitações LIST separadas:

  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  Não use o operador OR para combiná-los:

  (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

• Parênteses poderão ficar implícitos se você não os usar para agrupar restrições em um string de filtro. Por exemplo, a seguinte string de filtro:

  updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

  é interpretada como:

  updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")