updated readme

Azure-Samples · Dec 9, 2019 · f226a8b · f226a8b
1 parent 61bb43d
commit f226a8b
Showing 1 changed file with 135 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,18 @@
 ---
 page_type: sample
 languages:
-- csharp
+- python
+- tsql
+- sql
 products:
-- dotnet
-description: "Add 150 character max description"
-urlFragment: "update-this-to-unique-url-stub"
+- azure
+- vs-code
+- azure-sql-database
+description: "Creating a modern REST API with Python and Azure SQL, using Flask and Visual Studio Code"
+urlFragment: "azure-sql-db-python-rest-api"
 ---
 
-# Official Microsoft Sample
+# Creating a REST API with Python and Azure SQL
 
 <!-- 
 Guidelines on README format: https://review.docs.microsoft.com/help/onboard/admin/samples/concepts/readme-template?branch=master
@@ -18,36 +22,143 @@ Guidance on onboarding samples to docs.microsoft.com/samples: https://review.doc
 Taxonomies for products and languages: https://review.docs.microsoft.com/new-hope/information-architecture/metadata/taxonomies?branch=master
 -->
 
-Give a short description for your sample here. What does it do and why is it important?
+Thanks to native JSON support, creating a REST API with Azure SQL and Python is really a matter of a few lines of code. Take a look at `app.py` to easy it is!
 
-## Contents
+Wondering what's the magic behind? The sample uses the well known [Flask](https://flask.palletsprojects.com/en/1.1.x/) micro-framework and the [flask-restful](https://flask-restful.readthedocs.io/en/latest/) package to easily implement REST APIs. Beside that the [native JSON support that Azure SQL provides](https://docs.microsoft.com/en-us/azure/sql-database/sql-database-json-features) does all the heavy lifting so sending data back and forth to the database is as easy as sending a JSON message.
 
-Outline the file contents of the repository. It helps users navigate the codebase, build configuration and any related assets.
+## Install Sample Database
 
-| File/folder       | Description                                |
-|-------------------|--------------------------------------------|
-| `src`             | Sample source code.                        |
-| `.gitignore`      | Define what to ignore at commit time.      |
-| `CHANGELOG.md`    | List of changes to the sample.             |
-| `CONTRIBUTING.md` | Guidelines for contributing to the sample. |
-| `README.md`       | This README file.                          |
-| `LICENSE`         | The license for the sample.                |
+In order to run this sample, the WideWorldImporters database is needed. Install WideWorldImporters sample database:
 
-## Prerequisites
+[Restore WideWorldImporters Database](https://github.com/yorek/azure-sql-db-samples#restore-wideworldimporters-database)
 
-Outline the required components and tools that a user might need to have on their machine in order to run the sample. This can be anything from frameworks, SDKs, OS versions or IDE releases.
+## Add Database Objects
 
-## Setup
+Once the sample database has been installed, you need to add some stored procedure that will called from Python. The SQL code is available here:
 
-Explain how to prepare the sample once the user clones or downloads the repository. The section should outline every step necessary to install dependencies and set up any settings (for example, API keys and output folders).
+`./sql/WideWorldImportersUpdates.sql`
 
-## Runnning the sample
+If you need any help in executing the SQL script, you can find a Quickstart here: [Quickstart: Use Azure Data Studio to connect and query Azure SQL database](https://docs.microsoft.com/en-us/sql/azure-data-studio/quickstart-sql-database)
 
-Outline step-by-step instructions to execute the sample and see its output. Include steps for executing the sample from the IDE, starting specific services in the Azure portal or anything related to the overall launch of the code.
+## Run sample locally
 
-## Key concepts
+Make sure you have Python 3.7 installed on your machine. Clone this repo in a directory on our computer and than create a [virtual environment](https://www.youtube.com/watch?v=_eczHOiFMZA&list=PLlrxD0HtieHhS8VzuMCfQD4uJ9yne1mE6&index=34). For example:
 
-Provide users with more context on the tools and services used in the sample. Explain some of the code that is being used and how services interact with each other.
+```bash
+virtualenv venv --python C:\Python37\
+```
+
+then activate the created virtual environment. For example, on Windows:
+
+```powershell
+.\venv\Scripts\activate
+```
+
+and then install all the required packages:
+
+```bash
+pip install -r requirements
+```
+
+The connections string is not saved in the python code for security reasons, so you need to assign it to an environment variable in order to run the sample successfully. You also want to enable [development environment](https://flask.palletsprojects.com/en/1.1.x/config/#environment-and-debug-features) for Flask:
+
+Linux:
+
+```bash
+export FLASK_ENV="development"
+export SQLAZURECONNSTR_WWIF="<your-connection-string>"
+```
+
+Windows:
+
+```powershell
+$Env:FLASK_ENV="development"
+$Env:SQLAZURECONNSTR_WWIF="<your-connection-string>"
+```
+
+Your connection string is something like:
+
+```
+DRIVER={ODBC Driver 17 for SQL Server};SERVER=<your-server-name>.database.windows.net;DATABASE=<your-database-name>;UID=PythonWebApp;PWD=a987REALLY#$%TRONGpa44w0rd
+```
+
+Just replace `<your-server-name>` and `<your-database-name>` with the correct values for your environment.
+
+To run and test the Python REST API local, just run
+
+```bash
+flask run
+```
+
+Python will start the HTTP server and when everything is up and running you'll see something like
+
+```text
+ * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
+```
+
+Using a REST Client (like [Insomnia](https://insomnia.rest/), [Postman](https://www.getpostman.com/) or curl), you can now call your API, for example:
+
+```bash
+curl -X GET http://localhost:5000/customer/123
+```
+
+and you'll get info on Customer 123:
+
+```json
+[
+    {
+        "CustomerID": 123,
+        "CustomerName": "Tailspin Toys (Roe Park, NY)",
+        "PhoneNumber": "(212) 555-0100",
+        "FaxNumber": "(212) 555-0101",
+        "WebsiteURL": "http://www.tailspintoys.com/RoePark",
+        "Delivery": {
+            "AddressLine1": "Shop 219",
+            "AddressLine2": "528 Persson Road",
+            "PostalCode": "90775"
+        }
+    }
+]
+```
+
+Check out more samples to test all implemented verbs here:
+
+[cUrl Samples](./sample-usage.md)
+
+## Deploy to Azure
+
+Now that your REST API solution is ready, it's time to deploy it on Azure so that anyone can take advantage of it. A detailed article on how you can that that is here:
+
+- [Deploying Python web apps to Azure App Services](https://medium.com/@GeekTrainer/deploying-python-web-apps-to-azure-app-services-413cc16d4d68)
+- [Quickstart: Create a Python app in Azure App Service on Linux](https://docs.microsoft.com/en-us/azure/app-service/containers/quickstart-python?tabs=bash)
+
+The only thing you have do in addition to what explained in the above articles is to add the connection string to the Azure Web App configuration. Using AZ CLI, for example:
+
+```bash
+appName="azure-sql-db-python-rest-api"
+resourceGroup="my-resource-group"
+
+az webapp config connection-string set \
+    -g $resourceGroup \
+    -n $appName \
+    --settings WWIF=$SQLAZURECONNSTR_WWIF \
+    --connection-string-type=SQLAzure
+```
+
+Just make sure you correctly set `$appName` and `$resourceGroup` to match your environment and also that the variable `$SQLAZURECONNSTR_WWIF` as also been set, as mentioned in section "Run sample locally". An example of a full script that deploy the REST API is available here: `azure-deploy.sh`.
+
+## Learn more
+
+If you're new to Python and want to learn more, there is a full free Python curse here:
+
+- [Python for Beginners - Videos](https://aka.ms/python-for-beginners)
+- [Python for Beginners - GitHub Repo](https://github.com/microsoft/c9-python-getting-started)
+
+It will teach you not only how to use Python, but also how to take advantage the a great editor like Visual Studio Code.
+
+Flask is a very common (and amazing!) framework. Learn how to use it right from Visual Studio Code with this tutorial:
+
+[Flask Tutorial in Visual Studio Code](https://code.visualstudio.com/docs/python/tutorial-flask)
 
 ## Contributing