Utilizzo di LINQ per eseguire Query su documenti Cosmos DB dinamici

Il 9 luglio 2019 è stata annunciata una nuova serie di librerie per lavorare con i servizi Azure. Questi SDK (Software Development Kit, in italiano “pacchetto di sviluppo per applicazioni”), sono destinati a più linguaggi tra cui Python, Java, JavaScript e .NET. Alcuni servizi popolari sono coperti, tra cui anche Azure Cosmos DB.
Abbiamo deciso di provarli e di creare qualcosa di utile per un progetto di url shortner. Avere una dashboard è utile, ma l'aggiornamento dei dati è spesso oneroso. E se potessimo scrivere qualcosa di semplice e veloce per darci un’istantanea in tempo reale?

Per semplicità abbiamo iniziato da una app console, ma come ci siamo arrivati? Facciamo un passo indietro e ricominciamo insieme.

L’app console

Abbiamo deciso di scrivere in .NET Core multipiattaforma. Con già installato .NET Core SDK, abbiamo solo bisogno di creare una directory e iniziare una nuova applicazione console.

dotnet new console

Sconsigliano di mettere le credenziali nel codice sorgente, quindi le memorizziamo localmente su un file appSetting.json che non viene preso in considerazione dal tool di versionamento del codice grazie al file .gitIgnore. Ciò significa aggiungere il pacchetto di configurazione in modo che possiamo leggere le impostazioni:

dotnet add package
Microsoft.Extensions.Configuration.Json

Infine abbiamo aggiunto il nuovo Azure SDK per Cosmos DB.

dotnet add package Microsoft.Azure.Cosmos –version 3.0.0.19 -preview

Dopo di chè lanciamo Visual Studio Code e iniziamo!

code .

Connettersi

I nuovi SDK contengono molti esempi per iniziare, quindi abbiamo “preso in prestito” il codice principale da qui:


Azure Cosmos GitHub

Questo codice imposta un servizio di configurazione e inserisce le impostazioni:

IConfigurationRoot configuration = new ConfigurationBuilder()
    .AddJsonFile("appSettings.json")
    .Build();
string endpoint = configuration["EndPointUrl"];
if (string.IsNullOrEmpty(endpoint))
{
    throw new ArgumentNullException("Please specify a valid endpoint in the appSettings.json");
}

Ovviamente dobbiamo create il file appSettings.json e riempirlo:

{
    "EndPointUrl": "https://don't you wish.documents.azure.com:443",
    "AuthorizationKey": "DoodleDoodleDeeWubbaWubbaWubba=="
}

Per garantire che le impostazioni siano pubblicate localmente, abbiamo aggiunto alla configurazione .csproj:

<ItemGroup>
    <None Include="appSettings.json">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>

Il codice per creare il client è molto breve. Ciò crea un’istanza per il client e lo elimina al termine.

using (CosmosClient client = new CosmosClient(endpoint, authKey))
{
    await Program.RunQueryAsync(client);
}

L’abbiamo runnato a questo punto e non sono state lanciate eccezioni, quindi ovviamente sappiamo che era tempo di mandare in produzione. Err…

Apriamo il contenitore

Azure Cosmos DB organizza i dati in database account che contengono informazioni su aree, failover, tipo API da usare e altre proprietà. All’interno di un database è quindi possibile avere più contenitori partizionati e sottoposti ad approvvigionamento in modo diverso. Abbiamo un database chiamato url-tracking con un contenitore chiamato url-stats.

Abbiamo impostato questi nomi nel codice:

private static readonly string CosmosDatabaseId = "url-tracking";
private static readonly string containerId = "url-stats";

Suggerimento: Usiamo static readonly invece di const solo per abitudine. Potremmo voler spostare i valori in un file di configurazione in un secondo momento e con un static readonly possiamo inizializzare i valori all’avvio del processo rispetto a const che deve essere disponibile  al momento della compilazione.

Il database e il contenitore esistono già (questi sono i nostri dati di produzione, non una demo con dati di esempio) quindi per arrivare al contenitore il percorso è simile al seguente:

var cosmosDatabase = client.GetDatabase(CosmosDatabaseId);
var container = cosmosDatabase.GetContainer(containerId);
Console.WriteLine("Connected. Parsing entries now...");

Ora è il momento di estrarre i dati!

La forma dei dati
Ci sono alcune cose interessanti da sapere sui metadati del nostro contenitore. In quella che potrebbe essere stata una scelta di design scadente , anche se al momento sembra soddisfacente, abbiamo deciso di sfruttare il fatto che non abbiamo bisogno di uno schema fisso con NoSQL. Tracciamo un supporto che ci dice dove sono pubblicati i collegamenti (ad esempio, Twitter, Facebook o persino all’interno di una presentazione PowerPoint). Una esempio per Twitter potrebbe essere la seguente:

{
    "id": "unique guid goes here",
    "page": "azure.microsoft.com/blog/previewing-azure-sdks-following-new-azure-sdk-api-standards",
    "shortUrl": "F61",
    "campaign": "link",
    "referrerUrl": "t.co/4EXayhRpzF",
    "referrerHost": "t.co",
    "agent": "Mozilla/5.0 etc...",
    "browser": "Chrome",
    "browserVersion": "77",
    "browserWithVersion": "Chrome 77",
    "desktop": 1,
    "platform": "Windows",
    "platformVersion": "10",
    "platformWithVersion": "Windows 10",
    "count": 1,
    "timestamp": "2019-07-10T20:20:54",
    "host": "azure.microsoft.com",
    "twitter": 1
}

Se vogliamo fare la stessa cosa con LinkedIn, il codice sarebbe simile al seguente:

{
    "id": "unique guid goes here",
    "unimportant-stuff": "removed",
    "count": 1,
    "timestamp": "2019-07-10T20:20:54",
    "host": "azure.microsoft.com",
    "linkedin": 1
}

Notiamo che la proprietà è diversa in base al supporto. Tutto ciò rappresenta una sfida non da poco per l’analisi dei dati. I linguaggi dinamici come JavaScript lo gestiscono bene, ma che dire per linguaggi fortemente tipizzato come C#? Guardando a ritroso avremmo potuto semplificare l’intuitività della proprietà “jolly” facendo questo (notiamo la proprietà media aggiunta):

{
    "id": "unique guid goes here",
    "unimportant-stuff": "removed",
    "count": 1,
    "timestamp": "2019-07-10T20:20:54",
    "host": "azure.microsoft.com",
    "medium": "linkedin",
    "linkedin": 1
}

…o anche:

{
    "id": "unique guid goes here",
    "unimportant-stuff": "removed",
    "count": 1,
    "timestamp": "2019-07-10T20:20:54",
    "host": "azure.microsoft.com",
    "medium": {
        "linkedin": 1
    }
}

Ma non l’abbiamo fatto, quindi per ora la cosa migliore che potevamo inventare era guardare l’host. Ne parleremo a breve. Potremmo tornare indietro e scrivere un’utility per aggiornare la struttura dei dati in un secondo momento, ma per ora funziona bene.

La Query

Un vantaggio dell’API SQL di Azure Cosmos DB è il fatto che sia possibile usare la sintassi SQL per interrogare il documento. Questa è una query perfettamente valida:

SELECT * FROM c WHERE <filter> ORDER BY c.timestamp DESC

Tuttavia è preferibile usare LINQ perché non dobbiamo manipolare le stringhe e possiamo adottare un approccio più fluido.

Aspetta, di cosa parliamo quando c’è il nome LINQ? Se non conoscete C# e/o .NET, non temete. LINQ sta per Language Integrated Query. E’ un modo per scrivere query utilizzando i metodi C# senza ricorrere alla manipolazione delle stringhe. L’esempio di sopra diventa:

query.Select(c=>c).Where(c=>
{//filter}).OrderByDescending(c=>c.timestamp)

L’obbiettivo è semplice: prendere tutte le voci delle ultime 24 ore e aggregarle sulla pagina e sul supporto. Ordinarle per elencare prima la pagina più popolare con un conteggio totale di clic, quindi all’interno della pagina ordinare i medium più popolari e mostrare il punteggio. Per conservare i dati, creiamo questo:

var documents = new Dictionary<string,IDictionary<string,int>>();

Il dizionario degli indici viene ordinato per pagina, quindi all’interno della pagina è presente un dizionario nidificato indicizzato per mezzo e conteggio dei clic.
Successivamente, abbiamo creato la nostra query. Ecco la parte interessante del progetto: i nuovi SDK supportano completamente LINQ e non hanno problemi con dati dinamici! Invece di proiettare su un tipo dinamico, abbiamo usato un IDictionary <string, object> per emulare un “sacchetto delle proprietà” (le stringhe sono nomi di proprietà, gli oggetti i loro rispettivi valori). Il codice seguente imposta la query e crea un iteratore in modo da poter recuperare i risultati in modo asincrono. Si noti che è perfettamente corretto trasmettere il valore di un elemento nel dizionario su una proprietà DateTime.

var queryable = container
    .GetItemLinqQueryable<IDictionary<string, object>>();
var oneDay = DateTime.UtcNow.AddDays(-1);
var query = queryable
    .OrderByDescending(s => s["timestamp"])
    .Where(s => (DateTime)s["timestamp"] > oneDay);
var iterator = query.ToFeedIterator();

Ecco una LINQ query per voi.

Anche se il valore del dizionario è un tipo di oggetto, non dobbiamo bloccare uno schema specifico, l’SDK è abbastanza intelligente da serializzare i valori sui tipi .NET appropriati, in questo caso per il timestamp di un DateTime.

La strategia generica per scorrere i risultati è semplice e, per quanto ne sappiamo, gestisce automaticamente le richieste di limitazione in modo appropriato.

int entries = 0;
int pages = 0;
while (iterator.HasMoreResults)
{
    foreach(var document in await iterator.ReadNextAsync())
    {
        entries += 1;
        var page = document["page"].ToString();
        if (!documents.ContainsKey(page)) 
        {
            documents.Add(page, new Dictionary<string,int>());
            pages += 1;
        }
        // logica medium va qua
    }
}

Come potete vedere, chiediamo semplicemente se ci sono più risultati e quindi eseguiamo l’iterazione asincrona del feed. La logica per tenere traccia dei conteggi per medium non ha nulla a che fare con SDK, quindi vediamo il seguente esempio:

var pageData = documents[page];
bool medium = false;
foreach(var key in document.Keys)
{
    if (medium) {
        if (pageData.ContainsKey(key))
        {
            pageData[key] += 1;
        }
        else 
        {
            pageData[key] = 1;
        }
        break;
    }
    else {
        if (key == "host") {
            medium = true;
        }
    }
}

Stiamo trovando la proprietà dopo l’host e la stiamo usando per sommare i dati. Sì, questo richiede fiducia nell’ordinamento delle colonne ed è per questo che lo abbiamo spiegato in precedenza. Fortunatamente, se per qualche motivo la proprietà “jolly” non esiste, il loop uscirà dopo l’host.

Generare il rapporto

Ora che i dati sono stati raccolti, generare il rapporto finale è semplice, soprattutto con l’aiuto di LINQ.  Mostriamo i totali, poi ordiniamo le pagine per clic e al loro interno per il medium più cliccato:

onsole.WriteLine($"Parsed {pages} pages across {entries} entries.");
foreach (var page in documents
    .OrderByDescending(kv => kv.Value.Values.Sum())) 
{
    Console.WriteLine(
        $"Page: {page.Key}\n\t{page.Value.Values.Sum()}");
    foreach (var medium in page.Value
        .OrderByDescending(kv => kv.Value))
    {
        Console.WriteLine($"\t{medium.Key}:\t{medium.Value}");
    }
}

Facile no? Ci sono voluti circa 30 minuti per scrivere il codice e molto più tempo per scrivere il post sul blog. Facciamo runnare il nostro codice:

dotnet run

… e controlliamo come stanno procedendo le cose.

Considerazioni finali

I nuovi SDK sono arrivati e finora sembrano molto utili. Sono rapidi da mettere in funzione, l’API è sembrata intuitiva e gli esempi ci hanno aiutato a capire come risolvere il nostro problema. Non vediamo l’ora di vederli sviluppare a seconda dei feedback degli utenti e vedere più servizi usati nelle versioni future. Spero che abbiate trovato utile questo esempio come applicazione delle nuove SDK.
Buona giornata e buona programmazione a tutti!

FONTE: https://blog.jeremylikness.com/blog/using-linq-to-query-dynamic-schemaless-cosmosdb-documents/