sdk/python/using-mlflow/using-rest-api/using_mlflow_rest_api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "14420a34-d031-4fdd-87ec-b0d7c4cde3c9",
   "metadata": {},
   "source": [
    "# Using MLflow REST with Azure ML\n",
    "\n",
    "The MLflow REST API allows you to create, list, and get experiments and runs, and log parameters, metrics, and artifacts. The API is hosted under the `/api/2.0/mlflow` route on for Azure ML MLflow tracking URL."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "db40ba0f-e27d-4359-8941-08ecbb4e1140",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "361a8c77-4def-4600-ab27-f7136d933af1",
   "metadata": {},
   "source": [
    "## Getting an authorization token\n",
    "\n",
    "As with any Azure service, you need an authentication token to access the MLflow REST API. The following example shows how to get an authentication token using a service principal. You will need the tenant ID, client ID and client secret associated with the service principal. To create a service principal you can follow the steps at [Use the portal to create an Azure AD application and service principal that can access resources](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "818f3671-24f5-4c9c-828a-4819936b093d",
   "metadata": {},
   "outputs": [],
   "source": [
    "tenant_id = \"<TENANT_ID>\"\n",
    "client_id = \"<CLIENT_ID>\"\n",
    "client_secret = \"<CLIENT_SECRET>\"\n",
    "grant_type = \"client_credentials\"\n",
    "resource_scope = \"https://management.azure.com\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d24d089-7bf4-4075-b932-11b863b65762",
   "metadata": {},
   "source": [
    "The request URL is as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40e62292-d383-4c75-a47e-2bbf31ad4a7b",
   "metadata": {},
   "outputs": [],
   "source": [
    "mso_url = f\"https://login.microsoftonline.com/{tenant_id}/oauth2/token?\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69565bdc-2f80-4ef6-b61f-038023f05273",
   "metadata": {},
   "source": [
    "The service principal information is included inside the body:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "370a867d-c181-4722-b46d-1654b5f3e6d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "mso_body = f\"grant_type={grant_type}&client_id={client_id}&client_secret={client_secret}&resource={resource_scope}\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f0b7d62-490a-4481-87b6-7a0f2507af4c",
   "metadata": {},
   "source": [
    "Making the request and getting the token back:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d385481-670b-4d83-a302-fb09e338974f",
   "metadata": {},
   "outputs": [],
   "source": [
    "auth_response = requests.post(url=mso_url, data=mso_body)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "998667d1-4a74-4293-bfd3-e3d6f9f9ebcb",
   "metadata": {},
   "outputs": [],
   "source": [
    "token_data = auth_response.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "958a1f35-6f0b-465f-aeed-43b8b092998f",
   "metadata": {},
   "source": [
    "> Token is returned in the field `access_token`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "5ac77db1-5fb2-408a-b231-409820099494",
   "metadata": {},
   "source": [
    "## Querying the MLflow API\n",
    "\n",
    "You can get the MLflow API from the Azure portal or using the MLflow SDK as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6843777-77f0-4eca-8b05-f686cad0c757",
   "metadata": {},
   "outputs": [],
   "source": [
    "subscription_id = \"<SUBSCRIPTION_ID>\"\n",
    "resource_group = \"<RESOURCE_GROUP>\"\n",
    "workspace = \"<AML_WORKSPACE_NAME>\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "97cd9280",
   "metadata": {},
   "source": [
    "You can use the workspace object to get the tracking URI:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5a9af01a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from azure.ai.ml import MLClient\n",
    "from azure.identity import DefaultAzureCredential\n",
    "\n",
    "ml_client = MLClient(\n",
    "    DefaultAzureCredential(), subscription_id, resource_group, workspace\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bbebe3f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "azureml_tracking_uri = ml_client.workspaces.get(\n",
    "    ml_client.workspace_name\n",
    ").mlflow_tracking_uri"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b03f450-11ec-4bca-8e8e-80897a60b385",
   "metadata": {},
   "source": [
    "> You can get this URL following this steps: Navigate to Azure ML Studio and select the workspace you are working on > Click on the name of the workspace at the upper right corner of the page. > Click “View all properties in Azure Portal” on the pane popup. > Copy the MLflow tracking URI value from the properties section. Then replace the protocol from `azureml` to `https`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "5d20e51f",
   "metadata": {},
   "source": [
    "Once you have the tracking URI, the MLflow service URI is exactly the same, but with a different protocol:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a7bc088d",
   "metadata": {},
   "outputs": [],
   "source": [
    "azure_ml_mlflow_base = azureml_tracking_uri.replace(\"azureml://\", \"https://\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e06946d8",
   "metadata": {},
   "source": [
    "After the base path, the service is available in the following route:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "844f6996",
   "metadata": {},
   "outputs": [],
   "source": [
    "mlflow_api_path = \"api/2.0/mlflow\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa8995de-9a34-48ef-ab34-5344a11bb82f",
   "metadata": {},
   "source": [
    "Construct the request headers including the authentication token you just got:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4ce9abfe-bd6e-406b-b97a-879f6166adae",
   "metadata": {},
   "outputs": [],
   "source": [
    "headers = {\n",
    "    \"Content-Type\": \"application/json\",\n",
    "    \"Authorization\": f\"{token_data['token_type']} {token_data['access_token']}\",\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6b8f2d5e-aa0c-4fcd-b27f-bdddce80bdac",
   "metadata": {},
   "source": [
    "Construct the request URL as indicated at https://mlflow.org/docs/latest/rest-api.html. For example, the following URL list all the experiments in the workspace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "62197f71-9351-44bf-be42-bc326ea9e176",
   "metadata": {},
   "outputs": [],
   "source": [
    "response = requests.get(\n",
    "    f\"{azure_ml_mlflow_base}/{mlflow_api_path}/experiments/list\", headers=headers\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c51fdef9-58a2-4494-9107-a6c0d74f1560",
   "metadata": {},
   "source": [
    "In the following example, we are retrieving the experiments and parsing the results into a Pandas DataFrame for visualization:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "54623f31-8595-45f6-b5bd-61e9c53ee92f",
   "metadata": {},
   "outputs": [],
   "source": [
    "data = response.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c83ce105-3221-4d7c-abe2-c7f9d72ed394",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fdcdf0e8-9fed-45c9-b3d7-2888fb18e76c",
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.DataFrame(data[\"experiments\"])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10 - SDK V2",
   "language": "python",
   "name": "python310-sdkv2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}