Updates to document permission quickstarts

Author: HeidiSteen

Quickstart-Document-Permissions-Pull-API/document-permissions-pull-api.ipynb

@@ -26,6 +26,8 @@
     "\n",
     "## Permissions\n",
     "\n",
+    "This walkthrough uses Microsoft Entra ID authentication and authorization.\n",
+    "\n",
     "+ On Azure Storage, **Storage Blob Data Reader** permissions are required for both the search service identity and for your user account since you are testing locally. You also need **Storage Blob Data Contributor** because the sample includes code for creating and configuring a container and its contents.\n",
     "\n",
     "+ On Azure AI Search, assign yourself **Search Service Contributor**, **Search Index Data Contributor**, and **Search Index Data Reader** permissions to create objects and run queries. For more information, see [Connect to Azure AI Search using roles](https://learn.microsoft.com/azure/search/search-security-rbac) and [Quickstart: Connect without keys for local testing](https://learn.microsoft.com/azure/search/search-get-started-rbac).\n",
@@ -42,14 +44,17 @@
    "source": [
     "## Set up connections\n",
     "\n",
-    "Save the `sample.env` file as `.env` and then modify the environment variables to use your Azure endpoints. You need endpoints for:\n",
+    "Save the `sample.env` file as `.env` and then modify the environment variables to use your Azure endpoints. All variables must be specified.\n",
+    "\n",
+    "You need endpoints for:\n",
     "\n",
     "+ Azure AI Search\n",
     "+ Azure Storage\n",
     "\n",
     "For Azure AI Search, find the endpoint in the [Azure portal](https://portal.azure.com), in the **Essentials** section of the Overview page.\n",
     "\n",
-    "For Azure Storage, follow the guidance in [Get storage account configuration information](https://learn.microsoft.com/azure/storage/common/storage-account-get-info).\n",
+    "For Azure Storage, follow the guidance in [Get storage account configuration information](https://learn.microsoft.com/azure/storage/common/storage-account-get-info) to specify all of the variables in the `.env` file. \n",
+    "\n",
     "\n",
     "## Load Connections\n",
     "\n",
@@ -91,9 +96,7 @@
    "source": [
     "## Create an index\n",
     "\n",
-    "The search index must include fields for your content and for permission metadata. Assign the new permission filter option to a string field and make sure the field is filterable. The search engine builds the filter internally at query time.\n",
-    "\n",
-    "For local testing, `retrievable` should be **true** so that you can view the permission metadata, but be sure to change it back to **false** if you make the solution available to others."
+    "The search index must include fields for your content and for permission metadata. Assign the new permission filter option to a string field and make sure the field is filterable. The search engine builds the filter internally at query time."
    ]
   },
   {
@@ -112,8 +115,8 @@
     "    fields=[\n",
     "        SearchField(name=\"id\", type=\"Edm.String\", key=True, filterable=True, sortable=True),\n",
     "        SearchField(name=\"content\", type=\"Edm.String\", searchable=True, filterable=False, sortable=False),\n",
-    "        SearchField(name=\"oids\", type=\"Collection(Edm.String)\", filterable=True, retrievable=True, permission_filter=PermissionFilter.USER_IDS),\n",
-    "        SearchField(name=\"groups\", type=\"Collection(Edm.String)\", filterable=True, retrievable=True, permission_filter=PermissionFilter.GROUP_IDS),\n",
+    "        SearchField(name=\"oids\", type=\"Collection(Edm.String)\", filterable=True, permission_filter=PermissionFilter.USER_IDS),\n",
+    "        SearchField(name=\"groups\", type=\"Collection(Edm.String)\", filterable=True, permission_filter=PermissionFilter.GROUP_IDS),\n",
     "        SearchField(name=\"metadata_storage_path\", type=\"Edm.String\", searchable=True),\n",
     "        SearchField(name=\"metadata_storage_name\", type=\"Edm.String\", searchable=True)\n",
     "    ],\n",

Quickstart-Document-Permissions-Pull-API/sample.env

@@ -3,6 +3,6 @@ AZURE_SEARCH_INDEX=document-permissions-indexer-idx
 AZURE_SEARCH_INDEXER=document-permissions-indexer-idxr
 AZURE_SEARCH_DATASOURCE=document-permissions-indexer-ds
 AZURE_STORAGE_ACCOUNT_NAME=
-AZURE_STORAGE_CONTAINER_NAME=
+AZURE_STORAGE_CONTAINER_NAME=state-parks
 AZURE_STORAGE_CONNECTION_STRING=
 AZURE_STORAGE_RESOURCE_ID=

Quickstart-Document-Permissions-Push-API/document-permissions-push-api.ipynb

@@ -21,6 +21,22 @@
    "id": "b6585426",
    "metadata": {},
    "source": [
+    "## Prerequisites\n",
+    "\n",
+    "+ Azure AI Search, with [role-based access control](https://learn.microsoft.com/azure/search/search-security-enable-roles).\n",
+    "\n",
+    "## Permissions\n",
+    "\n",
+    "This walkthrough uses Microsoft Entra ID authentication and authorization.\n",
+    "\n",
+    "On Azure AI Search, you must have role assignments to create objects and run queries:\n",
+    "\n",
+    "+ **Search Service Contributor**\n",
+    "+ **Search Index Data Contributor**\n",
+    "+ **Search Index Data Reader**\n",
+    "\n",
+    "For more information, see [Connect to Azure AI Search using roles](https://learn.microsoft.com/azure/search/search-security-rbac) and [Quickstart: Connect without keys for local testing](https://learn.microsoft.com/azure/search/search-get-started-rbac).\n",
+    "\n",
     "## Set the environment variables\n",
     "\n",
     "1. Rename `sample.env` to `.env`.\n",
@@ -48,9 +64,9 @@
     "load_dotenv(override=True) # take environment variables from .env.\n",
     "\n",
     "# The following variables from your .env file are used in this notebook\n",
-    "endpoint = os.environ[\"AZURE_SEARCH_ENDPOINT\", \"\"]\n",
+    "endpoint = os.environ[\"AZURE_SEARCH_ENDPOINT\"]\n",
     "credential = DefaultAzureCredential()\n",
-    "index_name = os.getenv(\"AZURE_SEARCH_INDEX\", \"acl-sample\")\n",
+    "index_name = os.getenv(\"AZURE_SEARCH_INDEX\")\n",
     "token_provider = get_bearer_token_provider(credential, \"https://search.azure.com/.default\")\n"
    ]
   },
@@ -61,9 +77,7 @@
    "source": [
     "## Create Sample Index\n",
     "\n",
-    "The search index must includes fields for your content and for permission metadata. Assign the new permission filter option to a string field and make sure the field is filterable. The search engine builds the filter internally at query time.\n",
-    "\n",
-    "For local testing, `retrievable` should be **true** so that you can view the permission metadata, but be sure to change it back to **false** if you make the solution available to others."
+    "The search index must includes fields for your content and for permission metadata. Assign the new permission filter option to a string field and make sure the field is filterable. The search engine builds the filter internally at query time."
    ]
   },
   {

Quickstart-Document-Permissions-Push-API/sample.env

@@ -1,2 +1,2 @@
 AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
-AZURE_SEARCH_INDEX=acl-sample
+AZURE_SEARCH_INDEX=document-permissions-push-idx