{
 "cells": [
  {
   "cell_type": "code",
   "metadata": {
    "cell_style": "center"
   },
   "outputs": [],
   "source": [
    "# Copyright 2026 Google LLC\n",
    "#\n",
    "# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
    "# you may not use this file except in compliance with the License.\n",
    "# You may obtain a copy of the License at\n",
    "#\n",
    "#     https://www.apache.org/licenses/LICENSE-2.0\n",
    "#\n",
    "# Unless required by applicable law or agreed to in writing, software\n",
    "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    "# See the License for the specific language governing permissions and\n",
    "# limitations under the License.\n"
   ],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# RMI Tutorial 01: Cloud Project Setup & API Verification\n",
    "\n",
    "Welcome to the first module of the Roads Management Insights (RMI) tutorial series. This guide uses the `gcloud` CLI directly to initialize your environment.\n",
    "\n",
    "### Objectives:\n",
    "1. **Authenticate** with Google Cloud.\n",
    "2. **Set** your target project.\n",
    "3. **Identify** your Project Number.\n",
    "4. **Enable** the RMI service.\n",
    "5. **Manage** IAM permissions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googlemaps-samples/insights-samples/blob/main/roads_management_insights/tutorials/01_project_setup.ipynb) \n",
    "[![Open In Colab Enterprise](https://img.shields.io/badge/Open%20in-Colab%20Enterprise-blue?logo=google-cloud&logoColor=white)](https://console.cloud.google.com/vertex-ai/colab/import/https%3A%2F%2Fraw.githubusercontent.com%2Fgooglemaps-samples%2Finsights-samples%2Fmain%2Froads_management_insights%2Ftutorials%2F01_project_setup.ipynb) \n",
    "[![Open In BigQuery Notebooks](https://img.shields.io/badge/Open%20in-BigQuery%20Notebooks-blue?logo=google-cloud&logoColor=white)](https://console.cloud.google.com/bigquery/import?url=https%3A%2F%2Fraw.githubusercontent.com%2Fgooglemaps-samples%2Finsights-samples%2Fmain%2Froads_management_insights%2Ftutorials%2F01_project_setup.ipynb) \n",
    "[![View on GitHub](https://img.shields.io/badge/View%20on-GitHub-lightgrey?logo=github&logoColor=white)](https://github.com/googlemaps-samples/insights-samples/blob/main/roads_management_insights/tutorials/01_project_setup.ipynb)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Authentication\n",
    "Run the appropriate cell below depending on your environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Environment A: Google Colab\n",
    "Use this if you are running this notebook in your browser via colab.research.google.com."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from google.colab import auth\n",
    "auth.authenticate_user()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Environment B: Local Machine (Jupyter)\n",
    "Use this if you are running this notebook locally. Follow the interactive prompts to login."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!gcloud auth application-default login"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Project Configuration\n",
    "Set your target Google Cloud Project ID. Replace `YOUR_PROJECT_ID` with your actual ID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!gcloud config set project YOUR_PROJECT_ID"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Identify Project Number\n",
    "The RMI team requires your **numeric Project Number** for provisioning. The following command retrieves it automatically for the active project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Enable RMI API\n",
    "Enable the `roads.googleapis.com` service in your project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!gcloud services enable roads.googleapis.com"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. IAM Permission Management\n",
    "RMI requires specific roles for road selection and monitoring. \n",
    "\n",
    "### Understanding RMI Roles\n",
    "Run the cells below to see the specific technical permissions included in each role. This is particularly useful for developers who need to create **Custom IAM Roles** to meet strict organizational security policies. For more information on custom roles, see the [official Cloud documentation](https://cloud.google.com/iam/docs/creating-custom-roles)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Describe the Admin Role\n",
    "!gcloud iam roles describe roles/roads.roadsSelectionAdmin --format='json(includedPermissions)'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Describe the Viewer Role\n",
    "!gcloud iam roles describe roles/roads.roadsSelectionViewer --format='json(includedPermissions)'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check Current Permissions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!gcloud projects get-iam-policy $(gcloud config get-value project) \\\n",
    "  --flatten=\"bindings[].members\" \\\n",
    "  --format=\"table(bindings.role)\" \\\n",
    "  --filter=\"bindings.members:$(gcloud config get-value account) AND (bindings.role:roles/roads.roadsSelectionAdmin OR bindings.role:roles/roads.roadsSelectionViewer)\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grant RMI Role to a User\n",
    "Update the variables in the block below to grant permissions to a team member."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "MEMBER_EMAIL=\"user@example.com\"\n",
    "ROLE=\"roles/roads.roadsSelectionAdmin\"\n",
    "\n",
    "gcloud projects add-iam-policy-binding $(gcloud config get-value project) \\\n",
    "  --member=\"user:${MEMBER_EMAIL}\" \\\n",
    "  --role=\"${ROLE}\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grant RMI Role to a Service Account\n",
    "Update the variables below for automation identities."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "SA_EMAIL=\"service-account@PROJECT_ID.iam.gserviceaccount.com\"\n",
    "ROLE=\"roles/roads.roadsSelectionAdmin\"\n",
    "\n",
    "gcloud projects add-iam-policy-binding $(gcloud config get-value project) \\\n",
    "  --member=\"serviceAccount:${SA_EMAIL}\" \\\n",
    "  --role=\"${ROLE}\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary & Next Steps\n",
    "You have successfully initialized your project and verified your technical permissions using the `gcloud` CLI. \n",
    "\n",
    "**Next**: Proceed to the next tutorial to set up your first monitored route and begin receiving traffic insights."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "**For more advanced RMI query patterns, visit the official [RMI Sample Queries Repository](https://github.com/googlemaps-samples/insights-samples/tree/main/roads_management_insights/rmi_sample_queries).**"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}