开始使用 Cloudant

本文是 IBM Cloudant 系列教程的第一篇。本文是 Cloudant 的简介，解释了在使用 IBM Cloudant 时需要了解的初步知识。它还包含有关您在使用此数据库的解决方案中需要使用的基本 CRUD 操作的信息。

Clodant 是一种开源 NoSQL 数据库，它是一种同名分布式数据库。该服务基于开源项目 Apache CouchDB 和 BigCouch 项目。

本文是五篇文章中的第一篇，重点介绍如何开始使用 IBM Cloudant 以及如何在真实的物联网解决方案中使用它的实际示例。

虽然 Cloudant 可以与各种平台和语言一起使用，但本系列特别关注基于 .NET 和 Microsoft Azure 实现的解决方案。

这套教程将对各种专业人士非常有用

• 希望将 Cloudant 与 .NET 和/或 Microsoft Azure 一起使用的开发人员
• 在不同解决方案中使用 IBM Cloudant 的架构师
• 在物联网 (IoT) 解决方案上工作的各类专家（开发人员、架构师、业务分析师）

这些文章对于所有希望了解更多关于 Cloudant 和/或物联网解决方案的专家也很有用。

将提供示例的源代码供下载，以帮助读者更好地理解概念和实现细节。

背景

在过去的几年里，我们看到了越来越多的以数据为中心的解决方案，具有各种用例/需求，包括

• 能够以合理的价格存储大量数据
• 可扩展的数据存储
• 可以通过不同的属性进行搜索（支持多种索引）
• 数据库高度可用 - 能够就每年允许解决方案的最大停机时间提供服务水平协议 (SLA)
• 数据库作为 SaaS（软件即服务）实现，以提供进一步的支持和维护

所有这些要求都可以让你考虑一种特定的 NoSQL 数据库，并且是基于云的。这种解决方案是“特定的”，因为一方面我们需要使用通过不同索引进行搜索的分析，另一方面我们需要良好的可扩展性。对于这类解决方案，最佳选择之一是使用面向文档的数据库。该解决方案旨在存储、检索和管理面向文档的信息，也称为半结构化数据。

有几种流行的面向文档的数据库，如 MongoDB、CoachDB、DocumentDB、Cloudant（基于 CoachDB）。这些解决方案根据其云平台有不同的实现。IBM Cloudant 是本系列文章的主题。

必备组件

在开始之前，请确保您拥有

• Cloudant 账户
• Visual Studio 2015
• Microsoft Azure 账户

您需要有一个有效的 Cloudant 账户。如果您没有 IBM Cloudant 订阅，可以在 https://cloudant.com/ 创建一个。您可以免费试用此数据库 30 天。试用期结束后，Cloudant 提供按量计费，并且您每月的前 50 美元使用量免费。

当您设置 Cloudant 账户时，您会在“数据位置”部分注意到 Cloudant 可以部署在不同的云平台上。在本教程中，我们将使用部署在 Microsoft Azure 上的美国西部地区。但是，也可以使用包括 IBM SoftLayer 和 Rackspace 在内的其他云平台。

请记住，对于大多数解决方案，数据中心的地理位置（相对于您自己的解决方案）是选择数据位置时最重要的标准。通过选择离主要用户最近的数据中心，可以最大限度地减小数据中心与用户之间的网络延迟。

另一个重要的考虑因素可能是平台。了解定价结构（每个云平台的内部和外部流量收费不同），并为您的产品/解决方案选择最佳平台。

所有示例均以 C# 编写，并使用 Visual Studio 2015 实现。如果您没有 Visual Studio，社区版是一个不错的选择，可以从以下网址免费下载：https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx

最后，您需要一个 Microsoft Azure 账户。您可以在此处创建免费试用：https://azure.microsoft.com/en-us/free/

设置您的 Cloudant 数据库

以下是如何使用本文或代码的简要说明：类名、方法和属性，以及任何技巧或窍门。

登录 Cloudant 门户后，您可以看到现有的数据库。有两个预设数据库：\_users 和\_replicator，将在下一篇教程中讨论。

您也可以按名称过滤数据库。

您可以选择“创建数据库”控件来创建新数据库。之后，您需要输入新数据库的名称。名称只允许使用小写字母和数字。

创建新数据库后，可以通过门户使用查询来管理此数据库，或者通过更改索引、权限等来管理。

应用程序

为本系列文章创建的应用程序是一个简单的物联网解决方案，使用 C# 实现，包含以下部分（见下图）

• 托管对象（传感器），测量特定值，如温度、速度、位移等。
• 网关：收集传感器信息并通过以下方式进行通信的设备
• 后台系统 – 用于传入、处理和存储数据、管理和监控整个解决方案的一组服务和应用程序。

本文使用的简单原型包括

• 模拟网关（.NET 应用程序）
• 网关服务：一个在 .NET 中实现并托管在 Microsoft Azure 中的 Web 服务，它与网关通信并将数据存储到 IBM Cloudant。
• IBM Cloudant 数据库
• 用于可视化从 Cloudant 收集的数据的 Web 应用程序

Using the Code

创建了一个简单的 .NET 应用程序来演示通过 Cloudant REST API 进行基本的 CRUD 操作。源应用程序的整个源代码可在 GitHub 上找到。

应用程序在 IBM Cloudant 中保存 JSON 文档，并在读取这些文档后更新数据库中的文档。还演示了删除选项。

此应用程序非常基础，不使用任何特定框架。它仅使用 HttpClient 和 HttpClientHandler 通过 REST 接口与 Cloudant 数据库进行通信。HttpClient 是 .NET 的现代 HTTP 客户端。它提供了一个灵活且可扩展的 API，用于访问通过 HTTP 公开的所有内容。

需要注意的一些事项：

• HttpClientHandler 类用于实现 HTTP 处理程序。它是在响应 .NET Web 应用程序的请求时运行的过程（通常称为“终结点”）。
• 有一个辅助类 Sensor。它用于管理来自传感器的数据（我们将在下一篇教程的物联网解决方案中重用它）。
• 此类包含湿度、温度、位移以及从特定传感器测量这些值的时间的数据。
• 实现了一个名为“Generate”的种子方法来生成模拟传感器中的随机值。

#region Sensor
/// <summary>
/// Sensor class
/// this class is used to manage data from sensors
/// </summary>
public class Sensor
{
    public string time;
    public string dspl;
    public int temp;
    public int hmdt;

    static Random R = new Random();
    static string[] sensorNames = new[] { "sensorA", "sensorB", "sensorC", "sensorD", "sensorE" };

    public static Sensor Generate()
    {
        return new Sensor { time = DateTime.UtcNow.ToString(), dspl = sensorNames[R.Next(sensorNames.Length)], temp = R.Next(70, 150), hmdt = R.Next(30, 70) };
    }

    public static Sensor Update(Sensor sensor, string revision)
    {
        return new Sensor { time = sensor.time, dspl = sensor.dspl, temp = sensor.temp, hmdt = sensor.hmdt };
    }
}
#endregion Sensor

在主程序中，Cloudant 数据库的凭据作为参数传递。您需要创建一个 HttpClientHandler。它是一个 HttpMessageHandler，具有适用于大多数 HttpWebRequest API 版本的常用属性集。

此程序还添加了主要 CRUD 操作的实现。

static void Main(string[] args)

{

     //read config data from a command line parameters

     var user = args[0];

     var password = args[1];

     var database = args[2];


     //base request builder for all requests containing user name and database name

     var handler = new HttpClientHandler { Credentials = new NetworkCredential(user, password) };


     //create an http client

     using (var client = CreateHttpClient(handler, user, database))

     {

       //implement CRUD operations

     }

 }

CreatehttpClient 方法用于创建用于处理 CRUD 操作的 HttpClient。默认的 HttpClient 是开始发送请求的最简单方式。单个 HttpClient 可用于同时发送任意数量的 HTTP 请求，因此在许多情况下，您只需创建一个 HttpClient，然后将其用于所有请求。

#region CreateHttpClient
private static HttpClient CreateHttpClient(HttpClientHandler handler, string user, string database)
{
    return new HttpClient(handler)
    {
        BaseAddress = new Uri(string.Format("https://{0}.cloudant.com/{1}/", user, database))
    };
}
#endregion CreateHttpClient

下面的代码演示了如何通过简单的 JSON 文档提供 CRUD 操作。为了使代码更易于阅读，实现了四个辅助函数：“Create”、“Read”、“Update”、“Delete”。

#region manage simple json document

var creationResponse = Create(client, new { name = "john", age = 15 });
PrintResponse(creationResponse);

var id = GetString("id", creationResponse);
var readResponse = Read(client, id);
PrintResponse(readResponse);

var returnedObj = GetString(readResponse);
PrintDocument(returnedObj);
readResponse = Read(client, id);

var rev1 = GetString("_rev", readResponse);
var updateResponse = Update(client, id, new { name = "john", age = 36, _rev = rev1 });
PrintResponse(updateResponse);

var rev2 = GetString("rev", updateResponse);
var deleteResponse = Delete(client, id, rev2);
PrintResponse(deleteResponse);

#endregion manage simple json document

下面的代码演示了如何使用传感器数据管理 CRUD 操作。我们假设在下一篇教程的物联网解决方案中将使用类似的类。

#region manage data from sensors

//unfinite loop until esc key is pressed
Console.WriteLine("Press ESC to stop");
do
{
    while (!Console.KeyAvailable)
    {

        Sensor sensor = Sensor.Generate();
        var creationSensorResponse = Create(client, sensor);
        PrintResponse(creationSensorResponse);

        var _id = GetString("id", creationSensorResponse);
        var readSensorResponse = Read(client, _id);
        PrintResponse(readSensorResponse);

        var returnedSensorObj = GetString(readSensorResponse);
        PrintDocument(returnedSensorObj);

        readSensorResponse = Read(client, _id);
        rev1 = GetString("_rev", readSensorResponse);
        var updateSensorResponse = Update(client, _id, new { time = sensor.time, dspl = sensor.dspl, temp = sensor.temp, hmdt = sensor.hmdt, _rev = rev1 });
        PrintResponse(updateSensorResponse);
    }
} while (Console.ReadKey(true).Key != ConsoleKey.Escape);

#endregion manage data from sensors

下面显示了基本的 CRUD 辅助类：“Create”、“Read”、“Update”和“Delete”。

“Create”辅助方法。

#region Create
private static HttpResponseMessage Create(HttpClient client, object doc)
{
    var json = JsonConvert.SerializeObject(doc, Formatting.None);
    return client.PostAsync("", new StringContent(json, Encoding.UTF8, "application/json")).Result;
}
#endregion Create

“Read”辅助方法。

#region Read
private static HttpResponseMessage Read(HttpClient client, string id)
{
    return client.GetAsync(id).Result;
}
#endregion Read

“Update”辅助方法。

#region Update
private static HttpResponseMessage Update(HttpClient client, string id, object doc)
{
    var json = JsonConvert.SerializeObject(doc, Formatting.None);
    return client.PutAsync(id, new StringContent(json, Encoding.UTF8, "application/json")).Result;
}
#endregion Update

“Delete”辅助方法。

#region Delete
private static HttpResponseMessage Delete(HttpClient client, string id, string rev)
{
    return client.DeleteAsync(id + "?rev=" + rev).Result;
}
#endregion Delete

下面图片中展示了控制台应用程序。

使用辅助方法打印 HttpResponseMessage 和整个 JSON 文档。

您可以通过 Cloudant 管理门户选择数据库，并浏览或查询文档

选择特定文档，您可以看到 JSON 文档的完整内容。

摘要

本教程介绍如何开始使用 IBM Cloudant、如何创建账户、管理数据库以及如何使用 C# 和 .NET 实现一个可以通过 REST 接口管理 CRUD 操作的简单客户端。

下一部分将更侧重于 Cloudant HTTP API。我们将考虑如何使用此 API 实现一个简单的物联网解决方案。