feat(api_core): provide a 'raw_page' field for page_iterator.Page

[software-dov]

Some paginated response messages include additional fields that users
may wish to inspect. This change stores the raw page when constructing a page_iterator.Page and provides an accessor.

In addition to the new and modified unit tests, hand experimentation generates expected behavior:

fromgoogle.cloudimportautomlclient=automl.AutoMlClient()
result=client.list_datasets(...)
forpageinresult.pages:
print(f"{page.raw_page}")

prints individual pages.

[crwilcox]

Thanks @software-dov, any chance that this would be doable off of Iterator instead of Page so it could be used like:

response = client.list_resources(request)
handle_raw_response(p.raw_response)

[software-dov]

My two main concerns in no particular order are

1. As few differences from the surface exposed by the microgenerator as possible.
   If breaks are inevitable, prioritize breaks that don't require drastic changes in the microgenerator.
2. Ergonomic user interface

With "ease of implementation" being a non-voting tie-breaker.

Making the raw page (or transparently mapped attributes via getattr) visible from Iterator matches 1 with the minor caveat that 'page_token' isn't always a flattened parameter in either surface. I'm not entirely happy with the resulting interface, however.

With the microgenerator surface, touching internal fields of the page forces you to do your own pagination, something like

whileTrue:
response=client.paginated_method(request)
handle_page(response)
ifnotresponse.next_page_token:
breakrequest.page_token=response.next_page_token

which doesn't look great to me. Again, modulo complications with flattening, this is the interface that exposing raw_page in the iterator would be forced to mimic.

I guess I'm not sure I understand the circumstances where the topmost level raw_page is preferable to

response=client.paginated_method(request)
forpinresponse.pages:
handle_page(p)
foreltinp:
handle_element(elt)

[software-dov]

Open review and design bump

[tseaver]

LGTM pending greep CI (you can ignore the Cloud Build failure).