Merge pull request #563 from vespa-engine/kkraune/vespa-cloud-example

Add dataplane examples

docs/sphinx/source/getting-started-pyvespa-cloud.ipynb

@@ -98,7 +98,8 @@
    "id": "21598e61",
    "metadata": {},
    "source": [
-    "Create Vespa Cloud data-plane cert/key-pair:"
+    "Create Vespa Cloud data-plane cert/key-pair.\n",
+    "We save the paths to the credentials, for later dataplane access without using pyvespa APIs - see example at the end of this notebook."
    ]
   },
   {
@@ -116,12 +117,25 @@
     "!vespa auth cert -N"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 71,
+   "id": "64da11f2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cert_path = \"/Users/me/.vespa/mytenant.textsearch.default/data-plane-public-cert.pem\"\n",
+    "key_path  = \"/Users/me/.vespa/mytenant.textsearch.default/data-plane-private-key.pem\""
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d4f064e2",
    "metadata": {},
    "source": [
-    "Authenticate to get API key for deployment and save path for it:"
+    "Note that the subsequent deploy-call below will add `data-plane-public-cert.pem` to the application before deploying it.\n",
+    "\n",
+    "Authenticate to generate an API key for deployment, and save path for it:"
    ]
   },
   {
@@ -311,7 +325,19 @@
    "id": "aaae2f91",
    "metadata": {},
    "source": [
-    "`app` now holds a reference to a [Vespa](https://pyvespa.readthedocs.io/en/latest/reference-api.html#vespa.application.Vespa) instance."
+    "`app` now holds a reference to a [Vespa](https://pyvespa.readthedocs.io/en/latest/reference-api.html#vespa.application.Vespa) instance.\n",
+    "\n",
+    "Store the endpoint for later usage - paste from the deploy-output above:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7169d829",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "endpoint = \"https://textsearch-container.textsearch.mytenant.aws-us-east-1c.dev.z.vespa-app.cloud/\""
    ]
   },
   {
@@ -398,6 +424,121 @@
     "find more complex applications in\n",
     "[examples](https://pyvespa.readthedocs.io/en/latest/examples.html)."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "89400281",
+   "metadata": {},
+   "source": [
+    "## Example: Document operations using cert/key pair\n",
+    "\n",
+    "Above, we deployed to Vespa Cloud, and as part of that, generated a cert/key pair.\n",
+    "This pair can be used to access the dataplane for reads/writes to documents and running queries."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a32e2c83",
+   "metadata": {},
+   "source": [
+    "Find the ID of the first document in the feed:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9c8f83e6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.application import df_to_vespafeed\n",
+    "import json\n",
+    "\n",
+    "feed = json.loads(df_to_vespafeed(docs, app_name, \"id\", namespace=app_name))\n",
+    "doc_json = feed[0]\n",
+    "docid = doc_json[\"fields\"][\"id\"]\n",
+    "doc_json"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "562ac505",
+   "metadata": {},
+   "source": [
+    "Set up a dataplane connection using the cert/key pair:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ff72148c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import requests\n",
+    "\n",
+    "session = requests.Session()\n",
+    "session.cert = (cert_path, key_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7b69ff0d",
+   "metadata": {},
+   "source": [
+    "Get a document from the endpoint returned when we deployed to Vespa Cloud above:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "79f7d12c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "url = \"{0}/document/v1/{1}/{2}/docid/{3}\".format(endpoint, app_name, app_name, docid)\n",
+    "doc = session.get(url).json()\n",
+    "doc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "82888987",
+   "metadata": {},
+   "source": [
+    "Update the title and post the new version:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "21c7c399",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "doc[\"fields\"][\"title\"] = \"Can you eat lobster?\"\n",
+    "response = session.post(url, json=doc).json()\n",
+    "response"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "68ae7225",
+   "metadata": {},
+   "source": [
+    "Get the doc again to see the updated title:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2e3d560b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "doc = session.get(url).json()\n",
+    "doc"
+   ]
   }
  ],
  "metadata": {