HTTP API を統合する

Squid は、複雑な移行作業を必要とせずに、複数のデータソースから Squid のパワーを引き出すために、どんな API とも統合できます。

TL;DR

このチュートリアルでは、React と Squid を使用して、サンプルの Cat Facts API に接続し、ランダムな猫に関する事実を表示します。React と Squid プラットフォームの基本的な理解があると役立ちますが、このガイドには前提条件はありません。

アプリの完成版を確認するには、Squid HTTP API sample on GitHub をご覧ください。

新しい React プロジェクトを作成する

まず、このプロジェクトのすべてのファイルを格納する新しいディレクトリを作成します。

mkdir api

次に、ルートディレクトリに移動し、Vite を使用して新しい React TypeScript アプリケーションを作成します。これにより、プロジェクトのフロントエンドが作成されます。

npm create vite@latest api-frontend -- --template react-ts

次に、新しく作成されたディレクトリに移動し、すべての依存関係をインストールします:

cd api-frontend
npm install

コンソールで新しいアプリを作成する

Squid Console に移動し、api という名前の新しいアプリケーションを作成します.

注意

Squid では開発用と本番用の2つのターゲット環境を提供しています。このチュートリアルでは dev 環境を使用してください。ただし、prod 環境もオプションとして利用可能です。アプリケーションが正しく動作するように、プロジェクト全体で同じターゲット環境を使用していることを確認してください。詳細については Squid の environments をご覧ください.

コンソールの手順に従って、バックエンドのテンプレートプロジェクトを生成します。これらの手順を表示するには、概要ページの Initialize backend および Create .env file をクリックしてください。バックエンドを初期化する前に、フロントエンドとバックエンドのディレクトリが同じ階層になるように、ルートプロジェクトディレクトリに移動してください。

API インテグレーション (Connector) の作成

注意

本チュートリアルでは、integration と connector という用語は同義として使用されています。

コンソールで、アプリケーションの Connectors ページに移動し、新しい API connector を追加します。なお、connector は環境間で共有されないため、正しい環境 (おそらく開発の場合は dev) を使用していることを確認してください。

Add new API connector

2つの入力フィールドである Connector ID と OpenAPI specification URL に値を入力します:

ID には、このインテグレーションが表す内容を示す意味のある名前 (例: catFacts) を選択してください.
OpenAPI specification は API を文書化するための標準化された方法を提供します。URL は API によって提供され、API の home page で確認できます: https://catfact.ninja/docs?api-docs.json

この URL を指定することで、Squid が API との接続を確立します。Next ボタンをクリックすると、Squid が自動的に API Schema を検出するのを確認できます。API に変更があった場合は、手動で Rediscover schema を実行することも可能です (ただし、本チュートリアルでは必要ありません)。

Cat Facts API との接続を完了するために、インテグレーション画面の左上にある Base URL を編集します。Base URL はこの API のすべての利用可能なエンドポイントの初期パスを提供します。サンプルクエリを実行することで、API の home page で URL を確認できます。Cat Facts API の場合、URL は https://catfact.ninja です。
Save Schema をクリックして、API をプロジェクトに追加してください!

インテグレーションの理解

API インテグレーションを追加したので、次にその利用方法について理解を深めることができます。インテグレーションの Schema ページには、Squid が自動的に検出したすべてのエンドポイントが一覧表示されています。

例として、getRandomFact エンドポイントをクリックします.

Click getRandomFact endpoint

この画面では、各エンドポイントを利用するために必要な情報がすべて提供されています:

URL: このエンドポイントを使用するためのパスを示します。
Request: このエンドポイントに必要なオプションの一覧が提供されます。getRandomFact では、事実の max_length を指定する必要があります。
Injections: ヘッダーまたはボディに追加のフィールドを全リクエストに注入します。これにより、API Key のような秘密の値を格納できます。Cat Facts API は API Key を必要としないため、注入を追加する必要はありません。
Response: このエンドポイントを使用した後のレスポンスがどのようなものかを示します。getRandomFact では、レスポンスに猫の fact とその length の2つのフィールドが含まれます。

この情報を使って、プロジェクト内でインテグレーションを利用する準備が整いました。

セキュリティルール

外部 API インテグレーションにはセキュリティルールが必要です。これにより、インテグレーションや特定のエンドポイントへのアクセス認可のためのカスタムロジックを作成できます。このチュートリアルでは認証と認可は対象外となるため、catFacts インテグレーションへの全てのアクセスを許可するセキュリティルールを作成します。

ヒント

データの安全性についてさらに知りたい場合は、Squid のバックエンド security rules をご覧ください.

セキュリティルールは、api-backend/src/service/example-service.ts ファイルにあります。セキュリティルールは、SquidService クラスにデコレータを追加することで拡張できます。API インテグレーションのためのセキュリティルールを作成するには、パラメータとして INTEGRATION_ID を受け取る @secureApi デコレータを使用します。ExampleService クラスに新しいセキュリティルールを作成してください:

Backend code
import { secureApi, secureDatabase, SquidService } from '@squidcloud/backend';
import { ApiCallContext } from "@squidcloud/client";

...

export class ExampleService extends SquidService {

  ...

  @secureApi('catFacts')
  secureCatFacts(context: ApiCallContext): boolean {
    return true; // Allows all access to the catFacts integration
  }
}

クライアントで API を使用する

最後のステップは、React プロジェクト内で Squid React SDK を使用してインテグレーションを利用することです。

セットアップ

api-frontend ディレクトリ内で Squid React SDK をインストールします:

npm install @squidcloud/react

src/main.tsx で、.env ファイルに記載されている設定オプションを用いて、App コンポーネントを SquidContextProvider でラップします。.env ファイルは、コンソールでアプリを作成する際に自動生成されました.

Client code
import { SquidContextProvider } from '@squidcloud/react';


...

ReactDOM.createRoot(document.getElementById('root')!).render(
    <SquidContextProvider
      options={{
        appId: 'YOUR_APP_ID',
        region: 'YOUR_REGION', // example: 'us-east-1.aws'
        environmentId: 'dev | prod', // choose one of 'dev' or 'prod'
        squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
      }}
    >
      <App />
    </SquidContextProvider>
);

App.tsx

新しいインテグレーションを利用するために、src/App.tsx を編集します.

Squid React SDK の squid.api().request() メソッドを使用して、API インテグレーション内のエンドポイントを利用できます。request() メソッドは3つのパラメータを受け取ります:

integrationId: このインテグレーションは catFacts と命名しています
endpointId: コンソールで API の schema を発見した後、getRandomFact を使用します
body オブジェクト: リクエストには max_length が含まれている必要があることを、前述から確認しています

request() メソッドは promise を返します:

Client code
squid.api().request('catFacts', 'getRandomFact', { max_length: 70 });

このメソッドを App コンポーネント内で呼び出すことができます。まず、インテグレーションから返される事実をトラッキングするための React state を作成します。request 関数を呼び出すと、新しい事実データで state を更新できます。request が promise を返すため、promise が解決された後に .then メソッドでデータにアクセスする必要があります。React のテクニックとして、呼び出しを useEffect フックでラップし、一度だけ実行されるようにします。

Client code
function App() {
  const squid = useSquid();

  /* The endpoint's response object has a fact and its length. This can be
   * verified in the console */
  const [randomFact, setFact] = useState({ fact: '', length: 0 });

  useEffect(() => {
    squid
      .api()
      .request('catFacts', 'getRandomFact', { max_length: 70 })
      .then((data) => {
        setFact(data.body as RandomFact);
      });
  }, []);
}

catFact state の fact フィールドにアクセスして、ページに事実をレンダリングします。完全な App.tsx は以下の通りです:

Client code
import { useEffect, useState } from 'react';
import { useSquid } from '@squidcloud/react';
import './App.css';

interface RandomFact {
  fact: string;
  length: number;
}

function App() {
  const squid = useSquid();
  const [randomFact, setFact] = useState({ fact: '', length: 0 });

  useEffect(() => {
    squid
      .api()
      .request('catFacts', 'getRandomFact', { max_length: 70 })
      .then((data) => {
        setFact(data.body as RandomFact);
      });
  }, []);

  return (
    <>
      <div>
        Fact: {randomFact?.fact} <br />
        Length: {randomFact?.length}
      </div>
    </>
  );
}

export default App;

プロジェクトを実行する

プロジェクトを実行するには、クライアントの React プロジェクトとバックエンドの Squid プロジェクトの両方を起動する必要があります。

バックエンドを起動するには、api-backend フォルダから次のコマンドを実行します:

squid start

クライアントを起動するには、別のターミナルウィンドウを開き、ルートフォルダから次のコマンドを実行します:

npm run dev

ターミナルにログが表示されるポート (例: http://localhost:PORT) でクライアントプロジェクトが動作しているのが確認できます。ページには事実とその文字数が表示されます。新しいランダムな猫の事実を見るには、ページをリフレッシュしてください。

おめでとうございます! 数分で公式に Squid を使用した最初の API インテグレーションのセットアップが完了しました!

次のステップ

Squid API インテグレーションの機能についてさらに知りたい場合は、Client SDK documentation on calling an API をご覧ください。HTTP API エンドポイントのセキュリティをカスタマイズする方法については、Backend SDK documentation をご覧ください。

ボーナス: HTTP ヘッダーの組み込み

多くの場合、API インテグレーションでは、秘密情報を含む特殊なヘッダーが必要となります。Squid を使用すれば、これらの値をコンソールで迅速に設定し、セキュアなエンドポイントへのリクエストで安全に使用することができます。

これを実証するために、リクエストに API キーが必要な別の cat facts API を使用します。この API には利用可能な OpenAPI spec が存在しないため、スキーマを手動で追加する手順を説明する機会にもなります.

Random Cat Fact API を購読してください。この API には $0 の購読プランが利用可能です。RapidAPI アカウントをお持ちでない場合は、アカウントを作成する必要があります。購読により、RapidAPI キーを使用してエンドポイントに接続できるようになります.
Squid Console で、新しい HTTP API インテグレーションを追加します。インテグレーションには catFacts2 の ID を付けてください.
Add Connector をクリックします。この API には OpenAPI spec が存在しないため、Open API spec の URL は空のままにしてください.
エンドポイントの base URL を指定します: https://random-cat-fact.p.rapidapi.com.
Add endpoint をクリックし、エンドポイントに catFact という名前と相対パス / を設定します。HTTP メソッドは GET です.
Add endpoint をクリックして、エンドポイントを保存します.

この API では、X-RapidAPI-Key と X-RapidAPI-Host の2つのヘッダーが必要です。これらを Squid Console の API スキーマに追加しましょう.

Request 内の + をクリックして、X-RapidAPI-Key という名前のフィールドを追加します。フィールドの場所は HEADER です.

Add new field

再度 Request 内の + をクリックして、X-RapidAPI-Host という名前のフィールドを追加します。フィールドの場所は HEADER です.

Headers in console

クライアントからの呼び出しにこれらのヘッダーを追加する代わりに、Squid の injections 機能を使用して、エンドポイントからのすべての API 呼び出しに特定のフィールドを追加することができます。すべての呼び出しで X-RapidAPI-Key および X-RapidAPI-Host ヘッダーが必要なため、これらをスキーマの Injections セクションに追加します。API キーを安全に保つために、Squid Secrets を使用します.

Injections 内の + をクリックします。フィールド名に X-RapidAPI-Key を入力し、フィールドの場所として HEADER を選択します.
Is this a secret value? を On に切り替えます。すると、秘密を選択するためのドロップダウンが表示されます.
Select secret のドロップダウンで Create secret をクリックします.
Secret key として catFacts2 と入力します.
X-RapidAPI-Key の値を、RapidAPI page for the Random Cat Fact API からコピーし、秘密の値として貼り付けた後、Save をクリックします.
注入するフィールドを保存するために、Add field をクリックします.
再度 Injections 内の + をクリックします。今回はフィールド名を X-RapidAPI-Host とし、フィールドの場所として HEADER を選択します.
フィールドの値として random-cat-fact.p.rapidapi.com と入力し、Save をクリックします.

Injections in console

スキーマに行った全ての変更を保存するために、Save schema をクリックします.
Cat Facts アプリのフロントエンドで、App.tsx の現在の useEffect の機能を以下の内容に置き換えます:

Client code
useEffect(() => {
  squid
    .api()
    .request('catFacts2', 'catFact')
    .then((data) => {
      console.log(data);
      setFact({
        fact: data.body['fact'],
        length: JSON.stringify(data.body['fact']).length,
      } as RandomFact);
    });
}, []);

Squid バックエンドで、セカンドデコレータを追加して API へのアクセス認可の機能を追加します:

Backend code
  @secureApi('catFacts2')
  @secureApi('catFacts')
  secureCatFacts(context: ApiCallContext): boolean {
    return true;
  }

バックエンドで squid start、フロントエンドで npm run dev を実行して、新しいバージョンの Cat Facts アプリを実行してください。これで、アプリはセキュアな API エンドポイントからデータにアクセスできるようになりました!

これで、スキーマインジェクションと Squid Secrets を使用してセキュアな API エンドポイントにアクセスする方法が分かりました！ Squid HTTP API インテグレーションの利用可能な機能の詳細については、documentation on calling your API integration をご覧ください.

Squid は、複雑な移行作業を必要とせずに、複数のデータソースから Squid のパワーを引き出すために、どんな API とも統合できます。​

TL;DR​

新しい React プロジェクトを作成する​

コンソールで新しいアプリを作成する​

API インテグレーション (Connector) の作成​

インテグレーションの理解​

セキュリティルール​

クライアントで API を使用する​

セットアップ​

App.tsx​

プロジェクトを実行する​

次のステップ​

ボーナス: HTTP ヘッダーの組み込み​