原文:Getting Started With the MySQL REST Service Component

原著者:Miguel Araújo

本記事は、上記の英語記事をAIを使用して日本語に翻訳したものです。翻訳には誤訳や不正確な表現が含まれる可能性があります。内容の確認にあたっては英語原文を参照してください。


前回の記事では、MRS Componentを紹介し、Web開発者が保守するバックエンド・コードを減らしながらMySQLのデータにアクセスする方法を説明しました。今回は、顧客の注文を扱うREST APIを構築します。商品、注文、注文明細はリレーショナル・スキーマに格納されており、MRSは、それらの関連データをアプリケーションが利用できるネストしたJSONとして提供します。

コンポーネントを構成し、保護されたREST APIを通じて顧客の注文を公開します。その後、cURLを使ってMySQL Serverのアカウントでサインインし、注文とその明細を取得します。

スクリーンショットは、このREST APIを使って注文を表示し、配送メモを更新する、小規模なデモ用Webフロントエンドを示しています。

MySQLから取得したMiguelの注文#1001を表示するデモ・アプリケーション。注文とその明細を1回のリクエストで取得します。
デモ・アプリケーションに表示された、MySQLのMiguelの注文#1001。注文とその明細を1回のリクエストで取得します。

必要なもの

  • MySQL Server 26.10.0(MRS Componentを含みます)
  • MySQL Shell 26.10.0(MRSプラグインを同梱しています)

新しいローカル開発用インスタンスを使用してください。この例はLinuxでテストしています。MySQL Serverはターミナルと同じOSアカウントで実行し、127.0.0.1のポート3306にバインドして、MySQL接続のTLSを有効にしています。また、OpenSSL、cURL、およびJSON応答を整形するためのjqも必要です。

まず、インスタンスに合わせてポートとアカウントを調整し、管理者として接続します。

mysqlsh --host=127.0.0.1 --port=3306 --user=root --password

このShellセッションは開いたままにし、OpenSSLとcURLには2つ目のターミナルを使用してください。サンプルのパスワードと証明書は、このローカルでの演習用です。

1. MRSの構成

MRSはHTTPSでリクエストを処理します。ターミナルで、任意の場所にlocalhost用の証明書を作成してください。その場所は覚えておいてください。

openssl req -x509 -newkey rsa:2048 -sha256 -nodes \
  -days 30 -subj '/CN=localhost' \
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \
  -keyout localhost-key.pem -out localhost-cert.pem

chmod 600 localhost-key.pem

Serverを別のOSアカウントで実行している場合は、そのアカウントからアクセスできるディレクトリに両方のファイルを配置し、そのアカウントを秘密鍵の所有者に設定して、モード600を維持してください。また、cURLを実行するOSアカウントから証明書ファイルを読み取れることも確認してください。

MySQL ShellでMRSを構成し、コンポーネントをインストールします。必要に応じて\sqlでSQLモードに切り替えてください。以下の2つの証明書パスを、MySQL Serverプロセスから読み取れる絶対パスに置き換えます。

CONFIGURE REST METADATA;

INSTALL COMPONENT 'file://component_mysql_rest_service'
   SET PERSIST mysql_rest_service.ssl_cert = '/absolute/path/localhost-cert.pem',
       PERSIST mysql_rest_service.ssl_key = '/absolute/path/localhost-key.pem'; 

SHOW GLOBAL STATUS LIKE 'mysql_rest_service.state';

状態がREADYになれば、コンポーネントは稼働しています。その状態にならない場合は、MySQLのエラー・ログを確認してください。

2. 注文の公開

MRSが稼働したので、顧客の注文と、その明細および商品の詳細を、1つのネストしたJSONドキュメントとして返すAPIを構築しましょう。

ただし、その前にMySQL Shellでサンプル・データを作成します。注文1件、商品2件、およびそれらの注文明細です。

CREATE DATABASE shop;

CREATE TABLE shop.products (
    id INT PRIMARY KEY,
    name VARCHAR(100) NOT NULL
);

CREATE TABLE shop.orders (
    id INT PRIMARY KEY,
    customer_name VARCHAR(80) NOT NULL,
    ordered_at DATETIME NOT NULL,
    note VARCHAR(500) NOT NULL
);

CREATE TABLE shop.order_items (
    id INT PRIMARY KEY,
    order_id INT NOT NULL,
    product_id INT NOT NULL,
    quantity INT NOT NULL,
    unit_price DECIMAL(10,2) NOT NULL,
    FOREIGN KEY (order_id) REFERENCES shop.orders(id),
    FOREIGN KEY (product_id) REFERENCES shop.products(id)
);

INSERT INTO shop.products VALUES
    (1, 'Lukasz’s notebook'), (2, 'Scott’s coffee tumbler');

INSERT INTO shop.orders VALUES
    (1001, 'Miguel', '2026-10-06 09:30:00', 'Please leave with Sakila.');

INSERT INTO shop.order_items VALUES
    (1, 1001, 1, 2, 12.50), (2, 1001, 2, 1, 24.00);

サービスの作成とサインインの構成

次に、MySQLアカウント、RESTサービス、およびShopMySQLという名前の認証アプリを作成します。自動登録を無効にして、miguelをAPIに明示的に関連付けます。

CREATE USER 'miguel'@'localhost' IDENTIFIED BY 'Miguel-demo!26';

CREATE REST SERVICE /shop ENABLED PUBLISHED;
USE REST SERVICE /shop;

CREATE REST AUTH APP ShopMySQL VENDOR MYSQL
    DO NOT ALLOW NEW USERS TO REGISTER;

ALTER REST SERVICE /shop ADD AUTH APP ShopMySQL;

CREATE REST USER `miguel`@`ShopMySQL`
    OPTIONS {"vendor_user_id": "miguel@localhost"};

内部では何が起きているのでしょうか?

MySQL Serverがmiguelのパスワードを検証します。この場合、RESTユーザーは、そのMySQLアカウントをAPIに関連付ける役割を果たします。別のMRSパスワードを管理する必要はありません。このローカル構成では、miguel@localhostアカウントを使用します。

この手順では、MySQL Server認証を使用します。MRSは、MRSが管理するアカウントと、サポートされているOAuth2プロバイダーを通じたサインインにも対応しています。認可については、RESTロールがユーザーの実行できる操作を制御し、行の所有権ルールによって、自分自身のデータだけにアクセスを制限できます。詳しくは、認証と認可のドキュメントをご覧ください。

注文ドキュメントの定義

次に、MRSから返したいJSONドキュメントを記述します。外部キーによってテーブルが関連付けられ、RESTビューはそれらのデータを、items配列と各明細内の商品を含む注文の形に整えます。

CREATE REST SCHEMA /api ON SERVICE /shop FROM shop;

CREATE REST VIEW /orders ON SERVICE /shop SCHEMA /api
    AS shop.orders CLASS CustomerOrder @UPDATE {
        orderId: id @KEY,
        customerName: customer_name,
        orderedAt: ordered_at,
        note: note,
        items: shop.order_items {
            itemId: id @KEY,
            quantity: quantity,
            unitPrice: unit_price,
            product: shop.products {
                productId: id @KEY,
                name: name
            }
        }
    } AUTHENTICATION REQUIRED;

注意:@UPDATEは、このビューを通じた更新を有効にします。この手順では、配送メモを更新します。顧客向けAPIでは、価格や商品の詳細など、クライアントが変更してはいけない値を保護するために、フィールド・レベルの@NOUPDATEアノテーションを使用してください。

APIへのアクセス権の付与

/ordersを通じた読取りと更新を許可するRESTロールを作成し、miguelに割り当てます。

CREATE REST ROLE shop_user;

GRANT REST READ, UPDATE ON SCHEMA /api OBJECT /orders TO shop_user;

GRANT REST ROLE shop_user TO `miguel`@`ShopMySQL`;

ロールは操作を認可し、ビューは変更できるフィールドを定義します。両者を組み合わせることで、miguelは注文全体を取得し、その配送メモを更新できます。

この例では、HTTPS、MySQL Server認証、および明示的なREST権限を組み合わせています。手順の焦点を絞るために、アカウント1つと注文1件を使用します。複数の顧客が利用するアプリケーションでは、各顧客が自分自身の注文にしかアクセスできないよう、顧客ごとの認可を構成してください。

HTTPリクエストの認証には、miguelのMySQLアカウントを使用します。MRSは、そのデータ・アクセス用アカウントを通じて、構成されたクエリーを実行します。

3. 注文の取得

2つ目のターミナルでサインインし、セッションCookieを保存します。MRS_CAを、手順1で作成した証明書の絶対パスに置き換えてください。jqが環境変数からパスワードを読み取り、JSON形式のログイン・リクエストを組み立てる点に注目してください。

umask 077
MRS_URL='https://localhost:33443/shop'
MRS_CA='/absolute/path/localhost-cert.pem'

export MRS_PASSWORD='Miguel-demo!26'

jq -n '{
  authApp: "ShopMySQL",
  sessionType: "cookie",
  username: "miguel",
  password: env.MRS_PASSWORD
}' |
  curl --cacert "$MRS_CA" --cookie-jar miguel.cookies \
    --header 'Content-Type: application/json' \
    --data-binary @- \
    "$MRS_URL/authentication/login"

unset MRS_PASSWORD

ログイン・リクエストにはパスワードが含まれ、HTTPSが転送中のリクエスト全体を暗号化します。ログインと、その後の認証済みリクエストにHTTPSを使用する方法は、TLSによる認証の保護に関するOWASPの指針に沿っています。--cacertは、先ほど作成した証明書を使ってサーバー証明書を検証します。この使い捨てのパスワードは、ローカルでの演習にのみ使用してください。値を直接記述した代入はシェル履歴に残る可能性があり、環境変数は秘密情報の保管場所ではないことに注意してください。

ログインに成功するとHTTP 200 OKが返され、cURLがセッションCookieをmiguel.cookiesに保存します。このファイルは、後続のリクエストの認証に使用されるため、非公開にしてください。umask 077を設定すると、新しく作成するファイルの読取りと書込みを、自分のOSアカウントだけに許可できます。

なお、MRSはCookieの代わりに、Authorizationヘッダーを使ったJWT Bearerトークンにも対応しています。この方法は、今後の記事で取り上げます。

注意:MRSは構成の変更を自動的に取り込みます。設定直後の最初のログインで404が返される場合は、数秒待ってから、export MRS_PASSWORDを含め、上記のログイン用コード・ブロック全体を再実行してください。

次に、そのCookieを使って注文#1001を取得します。

curl --cacert "$MRS_CA" --cookie miguel.cookies \
  "$MRS_URL/api/orders/1001" | jq

応答には、注文、その明細、および商品の詳細が含まれます。

{
  "note": "Please leave with Sakila.",
  "items": [
    {
      "itemId": 1,
      "product": {
        "name": "Lukasz’s notebook",
        "productId": 1
      },
      "quantity": 2,
      "unitPrice": 12.5
    },
    {
      "itemId": 2,
      "product": {
        "name": "Scott’s coffee tumbler",
        "productId": 2
      },
      "quantity": 1,
      "unitPrice": 24.0
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/shop/api/orders/1001"
    }
  ],
  "orderId": 1001,
  "orderedAt": "2026-10-06 09:30:00.000000",
  "customerName": "Miguel",
  "_metadata": {
    "etag": "B1D2B69D23594853A8BBB85D4304D2C2DE87298144011BDEEC490D059193B83B"
  }
}

この応答には、デモで注文#1001を表示し、合計$49.00を計算するために必要な情報がすべて含まれています。ブラウザーは、商品の詳細も同じ応答で取得します。

ここで終了しても、読取りAPIは動作します。あるいは、以下の小さな更新を試すこともできます。

任意:配送メモの更新

同じAPIを使って、配送メモを変更してみましょう。まず、注文の最新のコピーを保存します。

curl --cacert "$MRS_CA" --cookie miguel.cookies \
  "$MRS_URL/api/orders/1001" --output order.json

テキスト・エディターでorder.jsonを開き、noteの値だけを次の内容に変更します。

"note": "Please leave with Rui or Alfredo. They'll handle the REST."

_metadata.etagを含め、ドキュメントの他の部分は変更しないでください。このバージョン識別子によって、MRSは注文が読取り後に変更されたかどうかを検出できます。

更新したドキュメントを、同じエンドポイントに送り返します。

curl --cacert "$MRS_CA" --cookie miguel.cookies \
  --request PUT --header 'Content-Type: application/json' \
  --data-binary @order.json "$MRS_URL/api/orders/1001"

注文を再度読み取り、保存されたメモを確認します。

curl --cacert "$MRS_CA" --cookie miguel.cookies \
  "$MRS_URL/api/orders/1001" | jq

更新したメモは、デモ・アプリケーションで次のように表示されます。

配送メモの更新を保存した後、注文を再読込みしたデモ・アプリケーション。
アプリケーションは保存後に注文を再度読み取ります。ページを再読込みすると、保存されたメモが表示されます。

変更をMySQLで直接確認するには、MySQL Shellセッションで次の文を実行してください。

SELECT id, note FROM shop.orders WHERE id = 1001;

更新を試した場合も、注文の読取りで終了した場合も、作業が終わったらサインアウトしてください。

curl --cacert "$MRS_CA" --cookie miguel.cookies \
  --request POST "$MRS_URL/authentication/logout"

まとめ

これで、MySQL Serverから直接提供される、顧客の注文を扱うAPIが動作するようになりました。認証済みリクエストを1回送信するだけで、注文、その明細、および商品の詳細がネストしたJSONとして返され、アプリケーションですぐに利用できます。任意の配送メモの更新まで実施した場合は、APIを通じてデータを変更し、その結果をMySQLで確認することもできました。

データはリレーショナル・スキーマに保持されたまま、MRSがアプリケーションに必要なドキュメントを提供します。HTTPSが接続を保護し、MySQL Serverがログインを検証し、RESTロールが許可された操作を制御します。複数の顧客が利用するアプリケーションでは、各顧客が自分自身の注文にしかアクセスできないよう、行の所有権ルールを構成することもできます。

自分のアプリケーションに役立つエンドポイントを1つ選び、それが返すドキュメントを定義して、最初のリクエストを送信してみてください。

次回のパート3「Inside MRS: From HTTP Request to MySQL and Back(MRSの内部:HTTPリクエストからMySQLへ、そして応答まで)」では、ルーティング、認証と認可、データベースでの実行、応答の生成という流れに沿って、リクエストの処理を追っていきます。

開発に参加する

最初のMRS APIで何を公開したいですか?この手順を試し、MySQL Community Slackで体験を共有してください。

MRS Componentのソース・コードを調べ、改善に貢献することもできます。開始方法は、コントリビューション・ガイドで説明しています。

不具合と機能の提案

問題を見つけた場合や機能の提案がある場合は、GitHubでIssueを作成するか、バグ・レポートを提出してください。

サポートが必要な場合は、サポート・チケットを作成してください。

詳細情報

ドキュメント

ダウンロード

ぜひお楽しみください。MySQLをご利用いただき、ありがとうございます。