API key
你的应用通过 API key 访问数据库:一个密钥和一个 secret,通过两个请求头发送。数据库、API key 和所有者都在 InceptionDB 控制台 中管理,使用你的 hola.cloud 账户登录。
创建数据库
在控制台中打开数据库选择器,选择 New database。大约一秒即可就绪。它的 ID 显示在概览页面上:这就是 INCEPTIONDB_DATABASE 的值。
创建 API key
- 选择数据库并打开 API keys & settings。
- 点击 New API key,以将使用它的应用命名,例如
backend-production。 - 复制 secret。它只显示一次:InceptionDB 只保存其哈希值。
控制台会给出可以直接使用的凭据,例如作为环境变量:
1export INCEPTIONDB_DATABASE="your-database-id"
2export INCEPTIONDB_API_KEY="your-api-key"
3export INCEPTIONDB_API_SECRET="your-api-secret"
一个 API key 可以访问其数据库中的所有集合,且只能访问这个数据库。
使用
在每个请求的 Api-Key 和 Api-Secret 请求头中发送密钥和 secret:
curl "https://inceptiondb.hola.cloud/v1/databases/$INCEPTIONDB_DATABASE/collections" \
-H "Api-Key: $INCEPTIONDB_API_KEY" \
-H "Api-Secret: $INCEPTIONDB_API_SECRET"GET /v1/databases/$INCEPTIONDB_DATABASE/collections HTTP/1.1
Host: inceptiondb.hola.cloud
Api-Key: $INCEPTIONDB_API_KEY
Api-Secret: $INCEPTIONDB_API_SECRET
// Go 1.21+, standard library only. Save as main.go and run: go run main.go
package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", "https://inceptiondb.hola.cloud/v1/databases/" + os.Getenv("INCEPTIONDB_DATABASE") + "/collections", nil)
if err != nil {
panic(err)
}
req.Header.Set("Api-Key", os.Getenv("INCEPTIONDB_API_KEY"))
req.Header.Set("Api-Secret", os.Getenv("INCEPTIONDB_API_SECRET"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(resp.Status)
fmt.Println(string(responseBody))
}
<?php
// PHP 8+ with the curl extension. Save as example.php and run: php example.php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://inceptiondb.hola.cloud/v1/databases/' . getenv('INCEPTIONDB_DATABASE') . '/collections',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Api-Key: ' . getenv('INCEPTIONDB_API_KEY'),
'Api-Secret: ' . getenv('INCEPTIONDB_API_SECRET'),
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $response, "\n";
curl_close($ch);
# Python 3.8+. Install: pip install requests. Save as example.py and run: python example.py
import os
import requests
headers = {
"Api-Key": os.environ["INCEPTIONDB_API_KEY"],
"Api-Secret": os.environ["INCEPTIONDB_API_SECRET"],
}
response = requests.request(
"GET",
"https://inceptiondb.hola.cloud/v1/databases/" + os.environ["INCEPTIONDB_DATABASE"] + "/collections",
headers=headers
)
print(response.status_code)
print(response.text)
// Node.js 18+. Save as example.mjs and run: node example.mjs
const response = await fetch("https://inceptiondb.hola.cloud/v1/databases/" + process.env.INCEPTIONDB_DATABASE + "/collections", {
method: "GET",
headers: {
"Api-Key": process.env.INCEPTIONDB_API_KEY,
"Api-Secret": process.env.INCEPTIONDB_API_SECRET
}
});
console.log(response.status);
console.log(await response.text());
// Java 17+, standard library only. Save as Main.java and run: java Main.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://inceptiondb.hola.cloud/v1/databases/" + System.getenv("INCEPTIONDB_DATABASE") + "/collections"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.header("Api-Key", System.getenv("INCEPTIONDB_API_KEY"))
.header("Api-Secret", System.getenv("INCEPTIONDB_API_SECRET"))
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}1[{"defaults":{"id":"uuid()"},"indexes":0,"name":"customers","total":2}]
密钥或 secret 错误时返回 403 Forbidden。
保证安全
- InceptionDB 是服务器到服务器的 API。不要在浏览器或移动应用中运行的代码里调用它:任何人都能在那里读到 secret。如果网页需要数据,让它调用你自己的后端,由后端保存 secret 并调用 InceptionDB。
- 把 secret 保存在服务器上,放在环境变量或密钥管理器中。不要放在代码、代码仓库、网页或移动应用中:任何看到它的人都能读取和修改你的数据。
- 每个应用或环境使用一个 API key。这样撤销其中一个不会影响其他的。
- 如果 secret 泄露,创建一个新密钥并部署,然后在 API keys & settings 中撤销旧密钥。被撤销的密钥立即失效。
所有者
所有者是通过控制台管理数据库的 hola.cloud 用户:管理其集合、API key 和其他所有者。在 API keys & settings 中添加或移除。数据库始终至少保留一个所有者,且你不能移除自己。
账户操作:仅限控制台
创建、重命名和删除数据库,以及管理 API key 和所有者,都在控制台中完成。API 参考 列出了这些端点,用于说明控制台做了什么,但它们不用于自动化:
Api-Key和Api-Secret对它们无效。API key 只能用于其数据库中的集合。- 它们需要已登录控制台的用户会话,在控制台之外没有受支持的获取方式。
查看控制台操作的代码
控制台中的每个操作都是一个 HTTP 请求,控制台会显示如何在你的代码中发出它。点击侧边菜单底部带有 { } 图标的 API calls。它会列出最近的请求;选择其中一个,即可看到 curl、Go、Python 等语言的版本,可直接复制。每个新请求还会在控制台右边缘的窄栏中显示为一个彩色圆点;点击圆点会打开同样的视图。
评论