Zero_touch_enrollment_customer_API.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "#### Copyright 2023 Google LLC.\n",
        "\n",
        "Licensed under the Apache License, Version 2.0 (the \"License\");"
      ],
      "metadata": {
        "id": "HQH5Ce3as0_r"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# 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."
      ],
      "metadata": {
        "id": "uan3m5ypuHW_"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Setup\n",
        "\n",
        "Follow [this guide](https://developers.google.com/zero-touch/guides/customer/service-accounts) to set up your service account.\n",
        "\n",
        "Download a service account key from the [Google Cloud Console](https://console.cloud.google.com) in JSON format.\n",
        "\n",
        "Upload this file using the 'Files' tab in the side menu of this colab, and rename the file to 'sa.json'."
      ],
      "metadata": {
        "id": "QKcn9AkqxuvE"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Set up the environment and authenticate with the service"
      ],
      "metadata": {
        "id": "kXF1u-RPiYv7"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "W6Vvl67N-GqB"
      },
      "outputs": [],
      "source": [
        "import json\n",
        "from apiclient import discovery\n",
        "import httplib2\n",
        "from oauth2client.service_account import ServiceAccountCredentials\n",
        "from google.protobuf import field_mask_pb2\n",
        "\n",
        "# A single auth scope is used for the zero-touch enrollment customer API.\n",
        "SCOPES = ['https://www.googleapis.com/auth/androidworkzerotouchemm']\n",
        "SERVICE_ACCOUNT_KEY_FILE = 'sa.json'\n",
        "\n",
        "def get_credential():\n",
        "  \"\"\"Creates a Credential object with the correct OAuth2 authorization.\n",
        "\n",
        "  Uses the service account key stored in SERVICE_ACCOUNT_KEY_FILE.\n",
        "\n",
        "  Returns:\n",
        "    Credentials, the user's credential.\n",
        "  \"\"\"\n",
        "  credential = ServiceAccountCredentials.from_json_keyfile_name(\n",
        "    SERVICE_ACCOUNT_KEY_FILE, SCOPES)\n",
        "\n",
        "  if not credential or credential.invalid:\n",
        "    print('Unable to authenticate using service account key.')\n",
        "  return credential\n",
        "\n",
        "\n",
        "def get_service():\n",
        "  \"\"\"Creates a service endpoint for the zero-touch enrollment API.\n",
        "\n",
        "  Builds and returns an authorized API client service for v1 of the API. Use\n",
        "  the service endpoint to call the API methods.\n",
        "\n",
        "  Returns:\n",
        "    A service Resource object with methods for interacting with the service.\n",
        "  \"\"\"\n",
        "  http_auth = get_credential().authorize(httplib2.Http())\n",
        "  return discovery.build('androiddeviceprovisioning', 'v1', http=http_auth)\n",
        "\n",
        "# Create a zero-touch enrollment API service endpoint.\n",
        "service = get_service()\n",
        "\n",
        "# Get the customer's account list, first page only.\n",
        "response = service.customers().list(pageSize=100).execute()\n",
        "\n",
        "if 'customers' not in response:\n",
        "  # No accounts found for the user. Confirm the Google Account\n",
        "  # that authorizes the request can access the zero-touch portal.\n",
        "  print('No zero-touch enrollment account found.')\n",
        "else:\n",
        "  for customer in response['customers']:\n",
        "    print(customer['name'] + \": \" + customer['companyName'])\n",
        "  CUSTOMER_ACCOUNT = response['customers'][0]['name']"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "# Specify a different customer account to use (optional)\n",
        "CUSTOMER_ACCOUNT = \"customers/xxxx\" # @param {type:\"string\"}\n"
      ],
      "metadata": {
        "id": "EORxQFZQ_T7P"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "\n",
        "\n",
        "---\n",
        "\n",
        "# DPCs"
      ],
      "metadata": {
        "id": "17hjlvquimm8"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Send an API request to list all the DPCs available using the customer\n",
        "# account.\n",
        "dpcResults = service.customers().dpcs().list(parent=CUSTOMER_ACCOUNT).execute()\n",
        "\n",
        "# Print out the details of each DPC.\n",
        "for i in range(0,len(dpcResults['dpcs'])):\n",
        "  # Some DPCs may not have a name, so replace with a marker.\n",
        "  if 'dpcName' in dpcResults['dpcs'][i]:\n",
        "    dpcName = dpcResults['dpcs'][i]['dpcName']\n",
        "  else:\n",
        "    dpcName = \"-\"\n",
        "  print('{0}: name:{1} dpcName:{2}  Package:{3}'.format(i, dpcResults['dpcs'][i]['name'], dpcName, dpcResults['dpcs'][i]['packageName']))\n",
        "\n",
        "DPC_NAME = dpcResults['dpcs'][0]['name']"
      ],
      "metadata": {
        "id": "-Hw0bYc2AD96"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "# Specify a different DPC to use (optional)\n",
        "\n",
        "DPC_NAME = \"customers/xxxx/dpcs/yyyy\" # @param {type:\"string\"}"
      ],
      "metadata": {
        "id": "FdBF8pcYkGB2"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "\n",
        "\n",
        "---\n",
        "\n",
        "\n",
        "# Configurations"
      ],
      "metadata": {
        "id": "TebSsE0w0BpO"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Create a configuration"
      ],
      "metadata": {
        "id": "Vh7CiBVxi4tB"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "CONFIGURATION_NAME = \"test\"\n",
        "CONFIGURATION_DPC_NAME = DPC_NAME\n",
        "CONFIGURATION_COMPANY_NAME = \"Test company\"\n",
        "CONFIGURATION_CONTACT_EMAIL = \"test@test.com\"\n",
        "CONFIGURATION_CONTACT_PHONE = \"5555555555\"\n",
        "CONFIGURATION_IS_DEFAULT = False\n",
        "\n",
        "configuration = {\n",
        "  \"companyName\": CONFIGURATION_COMPANY_NAME,\n",
        "  \"configurationName\": CONFIGURATION_NAME,\n",
        "  \"contactEmail\": CONFIGURATION_CONTACT_EMAIL,\n",
        "  \"contactPhone\": CONFIGURATION_CONTACT_PHONE,\n",
        "  \"dpcResourcePath\": CONFIGURATION_DPC_NAME,\n",
        "  \"isDefault\": CONFIGURATION_IS_DEFAULT\n",
        "}\n",
        "\n",
        "saved_configuration = service.customers().configurations().create(parent=CUSTOMER_ACCOUNT, body=configuration).execute()\n",
        "\n",
        "print(json.dumps(saved_configuration, indent=4))\n"
      ],
      "metadata": {
        "id": "tbvaJuKnXauN"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## List configurations"
      ],
      "metadata": {
        "id": "G3X1EnEIi8zY"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "configurations = service.customers().configurations().list(parent=CUSTOMER_ACCOUNT).execute()\n",
        "\n",
        "print(json.dumps(configurations, indent=4))"
      ],
      "metadata": {
        "id": "Dsa0Z1SRYaMN"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Set a configuration name to use in the following API calls"
      ],
      "metadata": {
        "id": "5EdEJLmlfw4z"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Copy 'name' field from the configuration list above\n",
        "\n",
        "CONFIGURATION_NAME = \"customers/xxxx/configurations/yyyy\" # @param {type:\"string\"}"
      ],
      "metadata": {
        "id": "MjXv4rXhfmQV"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Retrieve a named configuration"
      ],
      "metadata": {
        "id": "wNsynb4HjFwb"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "configuration = service.customers().configurations().get(name=CONFIGURATION_NAME).execute()\n",
        "\n",
        "print(json.dumps(configuration, indent=4))"
      ],
      "metadata": {
        "id": "orC7EkfybSDF"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Delete a named configuration"
      ],
      "metadata": {
        "id": "3mUxaCDNjJHX"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "service.customers().configurations().delete(name=CONFIGURATION_NAME).execute()"
      ],
      "metadata": {
        "id": "DlarZ89ncJRZ"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Patches (updates) a configuration"
      ],
      "metadata": {
        "id": "l1DZVylSjMvc"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# New values to update, or None to keep the same\n",
        "NEW_CONFIGURATION_NAME = \"New test\" # @param {type:\"raw\"}\n",
        "NEW_CONFIGURATION_DPC_NAME = None # @param {type:\"raw\"}\n",
        "NEW_CONFIGURATION_COMPANY_NAME = None # @param {type:\"raw\"}\n",
        "NEW_CONFIGURATION_CONTACT_EMAIL = None # @param {type:\"raw\"}\n",
        "NEW_CONFIGURATION_CONTACT_PHONE = None # @param {type:\"raw\"}\n",
        "NEW_CONFIGURATION_IS_DEFAULT = None # @param {type:\"raw\"}\n",
        "\n",
        "configuration = {\n",
        "}\n",
        "updateMask = field_mask_pb2.FieldMask()\n",
        "\n",
        "if (NEW_CONFIGURATION_NAME != None):\n",
        "  configuration['configurationName'] = NEW_CONFIGURATION_NAME\n",
        "  updateMask.paths.append('configuration_name')\n",
        "\n",
        "if (NEW_CONFIGURATION_DPC_NAME != None):\n",
        "  configuration['dpcResourcePath'] = DPC_NAME\n",
        "  updateMask.paths.append('dpc_resource_path')\n",
        "\n",
        "if (NEW_CONFIGURATION_COMPANY_NAME != None):\n",
        "  configuration['companyName'] = NEW_CONFIGURATION_COMPANY_NAME\n",
        "  updateMask.paths.append('company_name')\n",
        "\n",
        "if (NEW_CONFIGURATION_CONTACT_EMAIL != None):\n",
        "  configuration['contactEmail'] = NEW_CONFIGURATION_CONTACT_EMAIL\n",
        "  updateMask.paths.append('contact_email')\n",
        "\n",
        "if (NEW_CONFIGURATION_CONTACT_PHONE != None):\n",
        "  configuration['contactPhone'] = NEW_CONFIGURATION_CONTACT_PHONE\n",
        "  updateMask.paths.append('contact_phone')\n",
        "\n",
        "if (NEW_CONFIGURATION_IS_DEFAULT != None):\n",
        "  configuration['isDefault'] = NEW_CONFIGURATION_IS_DEFAULT\n",
        "  updateMask.paths.append('is_default')\n",
        "\n",
        "print(json.dumps(configuration, indent=4))\n",
        "print(updateMask.ToJsonString())\n",
        "\n",
        "saved_configuration = service.customers().configurations().patch(name=CONFIGURATION_NAME, body=configuration, updateMask=updateMask.ToJsonString()).execute()\n",
        "\n",
        "print(json.dumps(saved_configuration, indent=4))"
      ],
      "metadata": {
        "id": "t57hOUjqeP8N"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "\n",
        "\n",
        "---\n",
        "\n",
        "\n",
        "# Devices"
      ],
      "metadata": {
        "id": "Z_PoX6Wr0JYV"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Retrieve list of registered devices"
      ],
      "metadata": {
        "id": "peC3F1ThjTGf"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "devices = service.customers().devices().list(parent=CUSTOMER_ACCOUNT, pageSize=100).execute()\n",
        "\n",
        "print(json.dumps(devices, indent=4))"
      ],
      "metadata": {
        "id": "DOkhMtE0m_ha"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Retrieve a named device"
      ],
      "metadata": {
        "id": "Y5M7JvMMjYox"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "DEVICE_NAME = \"customers/xxxx/devices/yyyy\" # @param {type:\"string\"}\n",
        "\n",
        "device = service.customers().devices().get(name=DEVICE_NAME).execute()\n",
        "\n",
        "print(json.dumps(device, indent=4))"
      ],
      "metadata": {
        "id": "Iaw4pIIUsyXc"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Build a DeviceReference using a device id"
      ],
      "metadata": {
        "id": "cepd7TefhsPM"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Copy 'name' and 'deviceId' fields from the device list above\n",
        "\n",
        "DEVICE_ID = \"yyyy\" # @param {type:\"string\"}\n",
        "\n",
        "# Build a DeviceReference using the device id\n",
        "DEVICE_REFERENCE = {\n",
        "        'deviceId': DEVICE_ID\n",
        "    }"
      ],
      "metadata": {
        "id": "Pl800Duzhx4I"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Build a DeviceReference using the device identifiers (WiFi)"
      ],
      "metadata": {
        "id": "6mPtayrqjb0V"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Replace with real values\n",
        "DEVICE_MANUFACTURER = 'honeywell' # @param {type:\"string\"}\n",
        "DEVICE_MODEL = 'eda51' # @param {type:\"string\"}\n",
        "DEVICE_SERIAL = 'TESTTEST1234' # @param {type:\"string\"}\n",
        "\n",
        "DEVICE_REFERENCE = {\n",
        "        'deviceIdentifier': {\n",
        "            'manufacturer': DEVICE_MANUFACTURER,\n",
        "            'model': DEVICE_MODEL,\n",
        "            'serialNumber': DEVICE_SERIAL\n",
        "        }\n",
        "    }"
      ],
      "metadata": {
        "id": "VrqVIac9wN5L"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "\n",
        "## Build a DeviceReference using the device identifiers (cellular)"
      ],
      "metadata": {
        "id": "8KQwg4Csr_gp"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Replace with real value\n",
        "DEVICE_IMEI = '123456789012345' # @param {type:\"string\"}\n",
        "\n",
        "DEVICE_REFERENCE = {\n",
        "        'deviceIdentifier': {\n",
        "            'imei': DEVICE_IMEI\n",
        "        }\n",
        "    }"
      ],
      "metadata": {
        "id": "ytNJQzq4pZ4O"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Unclaim a device using the device reference"
      ],
      "metadata": {
        "id": "GSn1MJEljek5"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "body = {\n",
        "    'device': DEVICE_REFERENCE\n",
        "}\n",
        "\n",
        "service.customers().devices().unclaim(parent=CUSTOMER_ACCOUNT, body=body).execute()"
      ],
      "metadata": {
        "id": "1mSFL2ZvtpYB"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Apply a configuration to a device using the device reference"
      ],
      "metadata": {
        "id": "-sWl2iltjggD"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "body = {\n",
        "    'device': DEVICE_REFERENCE,\n",
        "    'configuration': CONFIGURATION_NAME\n",
        "}\n",
        "\n",
        "service.customers().devices().applyConfiguration(parent=CUSTOMER_ACCOUNT, body=body).execute()"
      ],
      "metadata": {
        "id": "qpzZ42MOvpum"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Remove a configuration from a device using the device reference"
      ],
      "metadata": {
        "id": "d1m4RU6PjiiW"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "body = {\n",
        "    'device': DEVICE_REFERENCE\n",
        "}\n",
        "\n",
        "service.customers().devices().removeConfiguration(parent=CUSTOMER_ACCOUNT, body=body).execute()"
      ],
      "metadata": {
        "id": "fRXmTcSPxadU"
      },
      "execution_count": null,
      "outputs": []
    }
  ]
}