Forem: Marcos Rivas

Cosmos DB CRUD operations using Azure Functions

Marcos Rivas — Sat, 06 Jun 2020 00:22:36 +0000

A few days ago I started working with Azure Functions and Cosmos DB from scratch, since natively these types of services work very well to integrate small query services without the need to implement much code. In this tutorial we will show you how to create CRUD operations using only Azure Functions and Cosmos DB to store and query the information.

Create a new database on Azure Cosmos DB

The first thing we need is to create a new Cosmos DB service. Cosmos DB is a service for the administration of non-SQL databases for the development of applications. It offers support for some of the most popular APIs like SQL, MongoDB and Cassandra.

Service creation

To provision a new database we need to do the following:

In the Azure main page let's a new resource.
We search for Azure Cosmos DB and click create.
We fill out the fields to complete the provision process
In Networking we mark the option Connectivity method as All Networks
In Encryption we mark the option Data Encryption as Service-managed key so Azure can handle the keys to connect to the service
We finish by clicking on Review + Create

Configure database and insert some data

Once we have the service activated we need to create the database, the collection, and insert some items. We are going to do the following:

Click on + Add Container in the Cosmos DB instance we created.
Set a database name. We can unselect the Provision database throughtput option, we don't need it for this tutorial.
Set a container name and one partition key. The partition key is a logic form to store information in Cosmos DB. You can find more information in the Microsoft documentation.
In my case I used the following names:
- Database id: dbtodos
- Container id: items
- Partition key: /all
Go to the Data Explorer section on the left menum to insert a new item
Click on New Item and we add two properties, title and completed. If we don't write an id property it's going to be generated automatically when we save the item.

Azure Functions creation

We are going to start creating our functions. We are going to create different Azure Functions for each of the operations that we have to implement. Every function is going to be configured with the bindings referencing our Cosmos DB instance, and we're going to see that for the operation of removing an element from our database we'll be using the @azure/cosmos module.

Function app creation

Search for Function App and click on create.
Configure the services as follows:
- Function App name: function-crud-cosmosdb
- Publish: Code
- Runtine stack: Node.js
- Version: 12
- Region: Central US
For Hosting section:
- Operating System: Windows
- Plan type: Consumption (Serverless)
Click on Review + Create

Application Settings configuration

Before starting, we have to configure some environment variables that will be used for communication between Azure Functions and Cosmos DB, this allows us to make requests to our database, This steps needs to be done only once for all out Azure functions.

Open your Cosmos DB service and click Keys on the left side menu.
Copy the string from URI, PRIMARY KEY and PRIMARY CONNECTION STRING. We are going to need these values later.
In the Function app, go to Application settings
Click on + New application setting to create a new setting.
Set a name and paste the PRIMARY CONNECTION STRING. In my case the setting is called cdb-vue-todos_DOCUMENTDB
Create another configuration and paste the URI string. (COSMOS_API_URL) and another one for the PRIMARY KEY (COSMOS_API_KEY) string.

Get items

Once the function is created, click on Functions and click on + Add.
Choose HTTP trigger so the function activates on every HTTP request.
Give a name to your function, mine is called getTodos. Authorization level is Anonymous.
Once the function is created go to Code + Test to configure the bindings and code.
On the editor select the function.json file and paste the following code:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "cosmosDB",
      "name": "inputDocument",
      "databaseName": "dbtodos",
      "collectionName": "items",
      "connectionStringSetting": "cdb-vue-todos_DOCUMENTDB",
      "partitionKey": "/all",
      "direction": "in"
    }
  ],
  "disabled": false
}

function.json is the file where we configure the bindings for our function. It's an array of objects where every object is a binding. The last object is the binding for our Cosmos DB database. It has configured with a cosmosDB type, and a variable associated to use in our code called inputDocument. The properties databaseName, collectionName, connectionStringSetting and partitionKey must have your own values.

With the parameter direction we can say if it's an input in or an output out. For this function an input binding means we can query our database. Given that we aren't specifying any additional query the function will return all objects.

In index.js we implement our code to manage the function. The binding has the inputDocument variable, that is where the results of our query are stored. We can show the items as a response.

module.exports = async function (context, req) {

    context.res = {
            // status: 200, /* Defaults to 200 */
            body: context.bindings.inputDocument
        };
};

If we test the URL to see the results we'll get the following:

Insert a new item

The next function has the same principle than the previous one, with only one change:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "cosmosDB",
      "name": "outputDocument",
      "databaseName": "dbtodos",
      "collectionName": "items",
      "createIfNotExists": false,
      "connectionStringSetting": "cdb-vue-todos_DOCUMENTDB",
      "partitionKey": "/all",
      "direction": "out"
    }
  ],
  "disabled": false
}

module.exports = async function (context, req) {

    const title = req.body.title; 
    const completed = req.body.completed; 

    if (title && completed != null) {

        context.bindings.outputDocument = req.body;
        context.res = {
            body: {'result': 'success'}
        };
    }else{
        context.res = {
            status: 400,
            body: {'result': 'error'}
        };
    }
};

This function works under POST requests. It expects two parameters in the body request to insert a new item in the database. If we don't set a title and completed parameter the function returns an error as a response, otherwise we use the variable outputDocument to assign the req.body object that has the values we want to insert.

Update an item

Repeat the steps 1 to 4 to create the updateTodo function. This is the binding:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "cosmosDB",
      "name": "inputDocument",
      "databaseName": "dbtodos",
      "collectionName": "items",
      "connectionStringSetting": "cdb-vue-todos_DOCUMENTDB",
      "partitionKey": "/all",
      "direction": "in",
      "sqlQuery": "select * from c where c.id = {id}"
    },
    {
      "type": "cosmosDB",
      "name": "outputDocument",
      "databaseName": "dbtodos",
      "collectionName": "items",
      "createIfNotExists": false,
      "connectionStringSetting": "cdb-vue-todos_DOCUMENTDB",
      "partitionKey": "/all",
      "direction": "out"
    }
  ],
  "disabled": false
}

The Javascript file is as follows:

module.exports = async function (context, req, todo) {

    const title = req.body.title;
    const completed = req.body.completed;

    context.bindings.outputDocument = todo[0];
    context.bindings.outputDocument.title = title
    context.bindings.outputDocument.completed = completed

    context.res = {
        body: {'result': 'success'}
    };
};

For this function we have an input and output binding. We use the input binding with a sql query to get the specific item to update, and then the output binding to change the values.

Notice that the input binding has a sqlQuery parameter where we can explicitly a SQL query to get an item based on the id "sqlQuery": "select * from c where c.id = {id}". There's a placeholder for id. When the function detects that there's an id in the http request this is going to be replaced on the placeholder.

The output binding is used to assign the item we got from the query. The result can be context.bindings.inputDocument or an additional parameter in our function, in this case the variable todo

Remove an item

For this function we need to do an additional implementation. Because we can't use the bindings to remove items from our database we need to use the @azure/cosmos module.

Go to the Function app > Developer tools. Click on Go
Go to Debug console > CMD and then in the diles list to site > wwwroot
Install the module using npm npm install @azure/cosmos
Close the window and go back to create your deleteTodo function.
We configure only the index.js file.

const cosmos = require('@azure/cosmos');
const endpoint = process.env.COSMOS_API_URL;
const key = process.env.COSMOS_API_KEY;
const { CosmosClient } = cosmos;

const client = new CosmosClient({ endpoint, key });
const container = client.database("dbtodos").container("items");

module.exports = async function (context, req) {
    const id = req.query.id;
    let res;
    try{
        res = await container.item(id).delete();
        context.res = {
            body: {'result': 'success'}
        };
    }catch(err){
        context.res = {
            status: 400,
            body: {'result': 'error'}
        };
    }

This is how the code works:

Create variables to import the Cosmos DB module and make reference to the application settings (COSMOS_API_URL y COSMOS_API_KEY).
Create a new instance of CosmosClient and set the key and endpoint.
Get the reference to the container and item.
Finally, execute the delete() method t finish the procedure.

Summary

Using Azure Functions with Cosmos DB allow us to execute queries and operations with minimal code and effort. This is just an introduction to understand how the bindings work and how easy is to connect to your database using a serverless service.

How to debug PHP using Visual Studio Code

Marcos Rivas — Mon, 13 Jan 2020 05:56:26 +0000

In this tutorial I'm going to teach you how to debug PHP using VS Code Debugger with simple steps.

1. PHP Debug extension

First of all we need to know we have to install an extension to be able to activate the PHP debugger in VS Code. The recommended extension is called PHP Debug. Something we need to notice is that this extension needs Xdebug to work.

2. Xdebug Installation

Xdebug is a PHP extension which provides debugging and profiling capabilities. It uses the DBGp debugging protocol. At this end this tool is responsible to enable the debugging on PHP, and Xcode takes advantage of it.

The debug information that Xdebug can provide includes the following:

Stack and function traces in error messages with:
Full parameter display for user defined functions
Function name, file name and line indications
Support for member functions
Memory allocation
Protection for infinite recursions

Xdebug also provides:

Profiling information for PHP scripts
Code coverage analysis
Capabilities to debug your scripts interactively with a debugger front-end.

Once we install the extension in Visual Studio Code let's configure Xdebug. Basically, we need to enable Xdebug in our computer to be capable of creating a new debugging profile in VS Code and can handle the debugging options when we want to debug our code.

Download Xdebug from the official site
If you are using Linux or Mac OS you need to follow this command to install using PECL:

 pecl install xdebug

And add the following line in the php.ini file:

zend_extension="/usr/local/php/modules/xdebug.so"

If you are using Windows, first of all, we need to get the php info of our installation. That's done creating a PHP file with a phpinfo() function. Copy all the source code and go to the installation wizard.

Paste the html code and see the result, you should get something like this:

You need to download a .dll file in the download section according to the PHP version and architecture. Using the wizard you can get the direct link to the file, both options are correct.
Download the file and copy it to your PHP installation folder to the
```
folder
```

We need to add the following line into our php.ini and restart your web server

zend_extension = <your_route>\php\ext\<the_filename_you_downloaded.dll>

And finally, enable the remote debugging by adding these lines to finish Xdebug configuration.

[XDebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1

3. Debugging configuration in VS Code

Now we have Xdebug configured, we need to finish the setup in VS Code.

Let's go to the Debug section and configure a new launch file.
Select PHP and you can see a default JSON configured. If you wish to change the name of the profile and port used for the debugger you can do it, if not, you can close the file.
And that's it! now you can set breakpoints into your code and active the debugging option to stop your web application and see your flow,

Summary

As you can see to activate the debugging feature for PHP is not as easy as install the extension, but I think the steps are really easy to follow. Please comment me if you were able to configure Xdebug to work with VS Code correctly, or if I missed an extra step to complete the setup.

And finally, thanks for reading my first post 😊. I would be gladded to hear your feedback and suggestions to improve my next post.