科技人筆記

Saturday, April 6, 2024

OData

OData（The Open Data Protocol）是一種基於REST的數據訪問方式，該標準由微軟發起，前三個版本1.0、2.0、3.0是微軟開放標準，第4.0版於2014年在OASIS投票通過成為開放工業標準。

The Open Data Protocol (OData) enables the creation of REST-based data services which allow resources, identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages.
This specification defines the core semantics and the behavioral aspects of the protocol.
OData - the Best Way to REST

OData‑URL

Odata定義了一組推薦的（但不是必需的）規則，用於構建URL以識別 OData 服務公開的數據和元數據，以及一組保留的URL查詢字串運算符。

Service root URL： url 的服務根是服務的基本 url。當對該 url 發出 GET 請求時，它將返回一個服務文檔，該文件定義了通過該服務可用的所有資源。 Redfish 的Service root URL 是 /redfish/v1 這在redfish spec中有定義
Resource path ： REST 定義的資源是可通過 HTTP 使用標準 GET、POST、PUT、PATCH 和 DELETE 方法訪問的物件。
Query options：查詢選項本質上是標準化的查詢字串參數，可以傳遞給 OData 服務以對請求的資源運行查詢。例如對資源的filter， count， skip， order， search 和 format。所有 OData 查詢選項都以 $ 符號為前綴，並且不區分大小寫。

另外在service root URL後面加上$metadata可以看到Service的實體模型（entity model），內容根據 [OData-CSDLJSON] 或 [OData-CSDLXML]

OData-CSDLXML

OData 服務是根據實體模型來描述的。 CSDL（Common Schema Definition Language）使用XML（Extensible Markup Language ）定義了由 OData 服務公開的實體數據模型的表示法，以及來自 W3C XML 模式定義語言的進一步構建塊（XSD）。

簡單來說，就是定義我們常聽到的Redfish的Schema和Property，這樣消費者可以知道它會得到的訊息格式，進而先處理（微軟有些tool可以直接將CSDL轉為結構或資料庫），這部分DMTF有CSDL的教學文件，同時也有一個Redfish Service Validator 的tool 來驗證我們的Redfish Services有沒有符合定義的CSDL

Redfish_School-Introduction_to_CSDL (dmtf.org)

GitHub - DMTF/Redfish-Service-Validator: The Redfish Service Validator is a Python3 tool for checking conformance of any "device" with a Redfish service interface against Redfish CSDL schema

OData-JSON

OData 定義一些特定的property 來擴展 JSON。舉一些常見的例子，詳細可以參閱Spec

@odata.id：entity-id與實體的規範URL相同，通常是必須存在的
@odata.count：計數控制資訊僅出現在回應中，可以註釋在任何集合中

定義 GitHub - openbmc/smbios-mdr

Redfish 简介

伺服器管理標準

基於 RESTful API

JSON 格式的 HTTPS

Schema-backed但可讀性高

Redfish 的誕生

Redfish 是在2015年由DMTF（Distributed Management Task Force）這個組織開始著手建立的伺服器管理標準，官方的描述是

A standard, Redfish is designed to deliver simple and secure management for converged, hybrid IT and the Software Defined Data Center (SDDC).
作為一項標準，Redfish 旨在為converged， hybrid IT 和 SDDC 提供簡單而安全的管理

這邊的 SDDC 就是"Software Defined Data Center （SDDC） - 軟體定義數據中心"，簡單來說就是希望未來能提供單一軟體工具集來管理這些虛擬化資源。但在伺服器的領域，長期發展且成熟的協定一直是IPMI，對於數據中心的管理者/客戶端的反饋是他們並不瞭解IPMI這個協定，他們的人員都需要重新學習，而且很多現代化的管理工具並不能直接應用在IPMI上面，所以Redfish誕生的契機就出現了

What is Redfish

用於 IT 基礎架構的行業標準 RESTful API
基於 Odata v4 的 JSON 格式的 HTTPS
應用程式、GUI 和腳本同樣可用
Schema-backed但可讀性高

Redfish Key technology HTTP

超文本傳輸協定（HTTP）是分散式、協作、超媒體資訊系統的應用層協定。它是一種通用、無狀態的協定，透過擴展其請求方法（Method）、錯誤代碼（Status-Code）和頭標（Header），可用於超文本之外的許多任務。

底下是HTTP協定的概念圖，詳細可以參考Hypertext Transfer Protocol -- HTTP/1.1，例如我們想要看Redfish 的Service root URL ，Request-Line就是 GET /redfish/v1 HTTP/1.1

我們可以透過回傳回應中的錯誤代碼（Status-Code）來判斷請求的狀態

常用的Method（GET， POST， PATCH， DELETE）

GET：獲取，例如獲取系統帳戶訊息GET /redfish/v1/AccountService
POST：

新增，例如新增一個帳戶 POST /redfish/v1/AccountService/Accounts {"id"："xxx" "password"："xxx"}
執行，例如執行韌體更新，開關機等動作

PATCH：更新，例如更新帳戶名字 PATCH /redfish/v1/AccountService/Accounts/01 {"Name"： "123"}
DELETE：刪除，例如刪除一個帳戶 DELETE /redfish/v1/AccountService/Accounts/01

常見的錯誤代碼（Status-Code）

Status-Code 是由三個數位所組合組成的，目的是企圖去理解和滿足請求

1xx：Informational （資訊）：提供協定級資訊
2xx：Success（成功）：用戶端請求被接受（成功）

200：OK
201： Created：申請資源創建成功
202：Accepted （已接受）：用於報告異步操作成功
204：No content （無內容）：當 API 想要發送空內容或沒有內容時響應體

3xx：Redirection （重定向）：用戶端請求由伺服器重定向到滿足客戶端請求的不同端點

301：Moved Permanently （永久移動）：用於重新定位的資源
302：Found （找到）

4xx：Client error（用戶端錯誤）：客戶端錯誤

400：Bad request （錯誤請求）
401：Unauthorized （未經授權）
403：Forbidden （禁止）
404：Not found （未找到）
405：Method not allowed （方法不允許）

5xx：Server error （伺服器錯誤）

500： Internal server error（內部伺服器錯誤）

HTTPS (Hyper Text Transfer Protocol Secure)

HTTPS 對在瀏覽器和網站之間發送的數據進行加密，使其比 HTTP 更安全，通信協定使用傳輸層安全性（TLS）或以前的安全套接字層（SSL）進行加密。 TLS的概念可以參考 [OpenBMC] LDAP 設定（三） - LDAPS（LDAP over TLS） TLS的部分

Restful API

OData

From: https://iris123321.blogspot.com/2022/02/10-redfish.html

Sunday, March 31, 2024

[Protocol] Android Bluetooth Architecture

[Protocol] D-Bus 原理

一个系统中可以有多条 D-Bus 总线，即多个 D-Bus 守护进程。D-Bus 总线有两种类型

个系统上可以存在任意多总线，以 Ubuntu 为例

System bus 系统总线

开机创建，有且只能有一条，Unix domain socket路径为/run/dbus/system_bus_socket

Session bus 用户总线

desktop environment，如：GNOME，KDE，每个用户登录后会创建专有的D-Bus总线，Unix domain socket路径为/run/user/$UID/bus

不同 Bus 之间是逻辑隔离的，相互直接无法通信。

原生物件和物件路徑

所有使用D-BUS的應用程式都包含一些物件, 當經由一個D-BUS連線收到一條訊息時，該訊息是被髮往一個物件而不是整個應用程式。在開發中程式框架定義著這樣的物件，例如JAVA，GObject，QObject等等，在D-Bus中成為native object

對於底層的D-Bus協議，即libdbus API，並不理會這些native object，它們使用的是一個叫做object path的概念。通過object path，高層程式設計可以為物件例項進行命名，並允許遠端應用引用它們。這些名字看起來像是檔案系統路徑，例如一個物件可能叫做

“/org/kde/kspread/sheets/3/cells/4/5”。易讀的路徑名是受鼓勵的做法，但也允許使用諸如“/com/mycompany/c5yo817y0c1y1c5b”等，只要它可以為你的應用程式所用。Namespacing的物件路徑以開發者所有的域名開始（如 /org/kde）以避免系統不同程式碼模組互相干擾。

方法和訊號Methodsand Signals

每一個物件有兩類成員：方法和訊號

方法就是 JAVA 中同樣概念，方法是一段函式程式碼，帶有輸入和輸出。

訊號是廣播給所有興趣的其他實體，訊號可以帶有資料 payload

在 D-BUS 中有四種型別的訊息

方法呼叫（method calls）、方法返回（method returns）、訊號（signals）和錯誤（errors）

要執行 D-BUS 物件的方法，您需要向物件傳送一個方法呼叫訊息。它將完成一些處理（就是執行了物件中的Method，Method是可以帶有輸入引數的。）並返回，返回訊息或者錯誤訊息。

訊號的不同之處在於它們不返回任何內容：既沒有“訊號返回”訊息，也沒有任何型別的錯誤訊息。

介面 Interface

每一個物件支援一個或者多個介面，介面是一組方法和訊號，介面定義一個物件實體的型別。D-Bus對介面的命名方式，類似org.freedesktop.Introspectable。開發人員通常將使用程式語言類的的名字作為介面名字。

Proxies代理

代理物件用來表示其他的remote object。當我們觸發了proxy物件的method時，將會在D-Bus上傳送一個method_call的訊息，並等待答覆，根據答覆返回。使用非常方便，就像呼叫一個本地的物件。