Iteradores de fluxo de resposta

O método search_stream retorna um iterador de SearchGoogleAdsStreamResponse objetos.

Iterar respostas de stream

É possível iterar cada GoogleAdsRow em cada resposta's results field, conforme mostrado no exemplo de código a seguir:

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )

A estrutura de cada GoogleAdsRow é determinada pelos campos selecionados na consulta da linguagem de consulta do Google Ads (GAQL). Para mais detalhes sobre a estrutura da resposta, consulte Linguagem de consulta do Google Ads.

Manter o iterador no escopo

Ao chamar GoogleAdsService.search_stream, um iterador de resposta de streaming é retornado. Esse iterador precisa permanecer no mesmo escopo do cliente GoogleAdsService enquanto estiver sendo consumido para evitar streams corrompidos ou falhas de segmentação. Isso ocorre porque o objeto Channel do gRPC subjacente é coletado como lixo assim que o objeto GoogleAdsService aberto sai do escopo. Se o objeto GoogleAdsService não estiver mais no escopo quando a iteração ocorrer no resultado de search_stream, o objeto Channel já poderá ser destruído, causando um comportamento indefinido quando o iterador tentar recuperar o próximo valor.

O código a seguir demonstra o uso incorreto de iteradores de stream:

def stream_response(client, customer_id, query):
    # The GoogleAdsService instance goes out of scope when this function
    # returns.
    ga_service = client.get_service(
        "GoogleAdsService", version="v26"
    )
    return ga_service.search_stream(customer_id=customer_id, query=query)


def main(client, customer_id):
    query = "SELECT campaign.name FROM campaign LIMIT 10"
    response = stream_response(client, customer_id, query=query)

    # Accessing the iterator in a different scope from where the service object
    # was created results in undefined behavior.
    for batch in response:
        print(batch)

Nesse código, o objeto GoogleAdsService é criado em um escopo diferente de onde o iterador é acessado. Como resultado, o objeto Channel pode ser destruído antes que o iterador consuma toda a resposta.

Em vez disso, mantenha o iterador de streaming no mesmo escopo do cliente GoogleAdsService enquanto ele estiver sendo usado:

def main(client, customer_id):
    ga_service = client.get_service(
        "GoogleAdsService", version="v26"
    )
    query = "SELECT campaign.name FROM campaign LIMIT 10"
    response = ga_service.search_stream(customer_id=customer_id, query=query)

    # Access the iterator in the same scope where the service object was
    # created.
    for batch in response:
        print(batch)