From b9c01b2f958a412898b2bf5e1357e2310f754e60 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Wed, 10 Jul 2024 22:07:31 +0000 Subject: [PATCH] docs: add partner attribution steps to integrations sample notebook --- notebooks/dataframes/integrations.ipynb | 138 ++++++++++++++++++------ 1 file changed, 104 insertions(+), 34 deletions(-) diff --git a/notebooks/dataframes/integrations.ipynb b/notebooks/dataframes/integrations.ipynb index 735e18d94e..9edb174f18 100644 --- a/notebooks/dataframes/integrations.ipynb +++ b/notebooks/dataframes/integrations.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "code", - "execution_count": 35, + "execution_count": 1, "metadata": {}, "outputs": [], "source": [ @@ -30,11 +30,47 @@ "This notebook demonstrates operations for building applications that integrate with BigQuery DataFrames. Follow these samples to build an integration that accepts a BigQuery DataFrames object or returns one." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Attributing requests initiated by BigQuery DataFrames\n", + "\n", + "Partners are required to attribute API calls to BigQuery and other Google APIs. Where possible, this should be done via the User-Agent string, but can also be done via job labels if your integration doesn't initialize the BigQuery DataFrames session.\n", + "\n", + "### Setting the User-Agent\n", + "\n", + "Set [`bpd.options.bigquery.application_name`](https://cloud.google.com/python/docs/reference/bigframes/latest/bigframes._config.bigquery_options.BigQueryOptions#bigframes__config_bigquery_options_BigQueryOptions_application_name) to a compliant string. Reach out to your Google Partner Engineering team contact for further instructions." + ] + }, { "cell_type": "code", - "execution_count": 36, + "execution_count": 2, "metadata": {}, "outputs": [], + "source": [ + "import bigframes.pandas as bpd\n", + "\n", + "# Set this to the string informed by your Google Partner Engineering team contact.\n", + "# Note: This can only be set once per session, so is most appropriate for partners\n", + "# who provide a Python + BigQuery DataFrames environment to their customers.\n", + "bpd.options.bigquery.application_name = \"notebook-samples/1.0.0 (GPN:notebook-samples)\"" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "/usr/local/google/home/swast/src/bigframes-2/bigframes/core/global_session.py:113: DefaultLocationWarning: No explicit location is set, so using location US for the session.\n", + " return func(get_global_session(), *args, **kwargs)\n" + ] + } + ], "source": [ "import bigframes.pandas as bpd\n", "\n", @@ -47,6 +83,40 @@ "}).set_index(\"index\")" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Setting the job label\n", + "\n", + "If your application works with customer-created BigQuery DataFrames objects, you might not be able to set the user-agent header because the session has already started (watch https://github.com/googleapis/python-bigquery-dataframes/issues/833 for updates on this limitation). Instead, attach a label to the jobs your application initiates, such as if you are performing `to_gbq()`on an existing DataFrame, as described below.\n", + "\n", + "Use `bpd.option_context()` so that the labels are only set during the operations your application performs." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "Query job eb7f3bbe-dda9-4d2f-b195-21de862d7055 is DONE. 0 Bytes processed. Open Job" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "with bpd.option_context(\"compute.extra_query_labels\", {\"application-name\": \"notebook-samples\"}):\n", + " table_id = df.to_gbq()" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -58,13 +128,13 @@ }, { "cell_type": "code", - "execution_count": 37, + "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/html": [ - "Query job 00b5c727-f2bf-4265-be22-d7d505619db7 is DONE. 0 Bytes processed. Open Job" + "Query job 4ad50c3c-91d0-4fef-91f6-0a2c5a30c38f is DONE. 0 Bytes processed. Open Job" ], "text/plain": [ "" @@ -76,10 +146,10 @@ { "data": { "text/plain": [ - "'swast-scratch._63cfa399614a54153cc386c27d6c0c6fdb249f9e.bqdf20240327_43bbc4c64fb947f7b69db570a5641506'" + "'swast-scratch._63cfa399614a54153cc386c27d6c0c6fdb249f9e.bqdf20240710_sessionf75568_9a045ff143db4f8ab2018994287020f3'" ] }, - "execution_count": 37, + "execution_count": 7, "metadata": {}, "output_type": "execute_result" } @@ -102,13 +172,13 @@ }, { "cell_type": "code", - "execution_count": 38, + "execution_count": null, "metadata": {}, "outputs": [ { "data": { "text/html": [ - "Query job f9c39ac2-a428-45c9-bb3a-643fc62a1c5b is DONE. 0 Bytes processed. Open Job" + "Query job 9e7d4b1a-d7fc-4599-bab4-40062c83288e is DONE. 0 Bytes processed. Open Job" ], "text/plain": [ "" @@ -122,11 +192,11 @@ "output_type": "stream", "text": [ " index int_col float_col string_col\n", - "0 2 3 0.2500 c\n", - "1 4 5 0.0625 e\n", + "0 3 4 -0.1250 d\n", + "1 1 2 -0.5000 b\n", "2 0 1 1.0000 a\n", - "3 1 2 -0.5000 b\n", - "4 3 4 -0.1250 d\n" + "3 4 5 0.0625 e\n", + "4 2 3 0.2500 c\n" ] } ], @@ -168,13 +238,13 @@ }, { "cell_type": "code", - "execution_count": 39, + "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ - "Query job ad53c7f2-e3bd-4667-b60b-b700c24b7a81 is DONE. 0 Bytes processed. Open Job" + "Query job 62db313e-7632-4dbb-8eff-5035d0e6c27e is DONE. 0 Bytes processed. Open Job" ], "text/plain": [ "" @@ -188,11 +258,11 @@ "output_type": "stream", "text": [ " index int_col float_col string_col\n", - "0 4 5 0.0625 e\n", - "1 0 1 1.0000 a\n", - "2 2 3 0.2500 c\n", - "3 3 4 -0.1250 d\n", - "4 1 2 -0.5000 b\n" + "0 1 2 -0.5000 b\n", + "1 3 4 -0.1250 d\n", + "2 0 1 1.0000 a\n", + "3 4 5 0.0625 e\n", + "4 2 3 0.2500 c\n" ] } ], @@ -265,13 +335,13 @@ }, { "cell_type": "code", - "execution_count": 40, + "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/html": [ - "Query job 2aa7033c-c547-4ae2-a9aa-33272be82b9c is DONE. 0 Bytes processed. Open Job" + "Query job 1cbd8898-97c7-419e-87af-b72a9432afb6 is DONE. 0 Bytes processed. Open Job" ], "text/plain": [ "" @@ -283,10 +353,10 @@ { "data": { "text/plain": [ - "'swast-scratch._63cfa399614a54153cc386c27d6c0c6fdb249f9e.bqdf20240327_b484a3967fba4a41850f4eb21b4b3bd8'" + "'swast-scratch._63cfa399614a54153cc386c27d6c0c6fdb249f9e.bqdf20240710_sessionf75568_58b9b6fc0c3349bf8d3dd6fb29ab5322'" ] }, - "execution_count": 40, + "execution_count": 9, "metadata": {}, "output_type": "execute_result" } @@ -308,13 +378,13 @@ }, { "cell_type": "code", - "execution_count": 41, + "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/html": [ - "Query job 1d489f94-2840-405e-9114-d439dcfcf7aa is DONE. 0 Bytes processed. Open Job" + "Query job 40e54aa9-fad7-47c3-9bec-144f6c7106d8 is DONE. 0 Bytes processed. Open Job" ], "text/plain": [ "" @@ -326,10 +396,10 @@ { "data": { "text/plain": [ - "'swast-scratch._63cfa399614a54153cc386c27d6c0c6fdb249f9e.bqdf20240327_d00699eeeed743b487c870dca5bcf23b'" + "'swast-scratch._63cfa399614a54153cc386c27d6c0c6fdb249f9e.bqdf20240710_sessionf75568_cdb4f54063b0417a8309c462b70239fa'" ] }, - "execution_count": 41, + "execution_count": 10, "metadata": {}, "output_type": "execute_result" } @@ -357,7 +427,7 @@ }, { "cell_type": "code", - "execution_count": 42, + "execution_count": 11, "metadata": {}, "outputs": [ { @@ -366,7 +436,7 @@ "Dataset(DatasetReference('swast-scratch', 'my_dataset'))" ] }, - "execution_count": 42, + "execution_count": 11, "metadata": {}, "output_type": "execute_result" } @@ -381,13 +451,13 @@ }, { "cell_type": "code", - "execution_count": 43, + "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "text/html": [ - "Query job 40977e60-97c3-4c93-89e2-d7334e5af71d is DONE. 0 Bytes processed. Open Job" + "Query job 73cf9e04-d5fa-4765-827c-665f0e6b9e00 is DONE. 0 Bytes processed. Open Job" ], "text/plain": [ "" @@ -399,7 +469,7 @@ { "data": { "text/html": [ - "Query job 81e35bb8-2e27-4a18-b596-15a7805331f0 is DONE. 270 Bytes processed. Open Job" + "Query job b177eb37-197f-4732-8978-c74cccb36e01 is DONE. 270 Bytes processed. Open Job" ], "text/plain": [ "" @@ -523,7 +593,7 @@ "[10 rows x 3 columns]" ] }, - "execution_count": 43, + "execution_count": 12, "metadata": {}, "output_type": "execute_result" } @@ -627,7 +697,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.1" + "version": "3.10.9" } }, "nbformat": 4,