HTTP API を統合する

Squid はあらゆる API と統合でき、複雑な移行を行わなくても、複数のデータソースで Squid の力を活用できます。

TL;DR

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

完成版のアプリを確認するには、GitHub の Squid HTTP API sample を参照してください。

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

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

mkdir api

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

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

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

cd api-frontend
npm install

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

Squid Console に移動し、api という名前で新しい application を作成します。

Note

Squid には development と production の 2 つの target environment があります。このチュートリアルでは dev environment を使用しますが、prod も選択可能です。アプリケーションが動作するように、プロジェクト全体を通して同じ target environment を使用していることを確認してください。詳細は、Squid のenvironmentsを参照してください。

コンソールの手順に従って backend テンプレートプロジェクトを生成します。これらの手順を表示するには、Overview ページで Initialize backend と Create .env file をクリックします。backend を初期化する前に、必ずルートのプロジェクトディレクトリに cd で戻り、frontend と backend のディレクトリが兄弟（同階層）になるようにしてください。

API Connector を作成する

Note

このチュートリアルでは、「integration」と「connector」という用語を同じ意味で相互に使用しています。

コンソールで、アプリケーションの Connectors ページに移動し、新しい API connector を追加します。connectors は environment 間で共有されないため、正しい environment（開発用途なら通常 dev）を使用していることを確認してください。

Add new API connector

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

ID には、この connector が表すものが分かる意味のある値（例: catFacts）を選びます
OpenAPI specification は API を標準化された方法でドキュメント化する仕組みです。URL は API 側から提供されており、API のホームページで確認できます: https://catfact.ninja/docs?api-docs.json

この URL を指定することで、Squid が API へ接続します。Next ボタンをクリックすると、Squid が API Schema を自動的に検出します。 API に変更があった場合は、手動で Rediscover schema を実行することもできます（ただし、このチュートリアルでは不要です）。

Cat Facts API への接続を完了するには、connector 画面左上の Base URL を編集します。base URL は、この API で利用可能なすべての endpoint の起点となるパスです。URL は API のホームページでサンプルクエリを実行すると確認できます。Cat Facts API の場合は https://catfact.ninja です。
Save Schema をクリックして、API をプロジェクトに追加します。

Connector を理解する

API connector を追加できたので、次は使い方を理解していきます。connector の Schema ページには、Squid が自動検出したすべての endpoint が一覧表示されます。

例として、getRandomFact endpoint をクリックします。

Click getRandomFact endpoint

この画面には、各 endpoint を利用するために必要な情報がすべて含まれています。

URL: この endpoint を利用するためのパスを示します。
Request: この endpoint に必要なオプションの一覧です。getRandomFact では、fact の max_length を指定する必要があります。
Injections: その endpoint のすべての request に対して、header または body に追加フィールドを注入（inject）します。API Key のような secret 値を保存する用途にも使えます。Cat Facts API は API Key を必要としないため、injection の追加は不要です。
Response: この endpoint を呼び出した後の response の形を示します。getRandomFact の response には 2 つのフィールド（猫の fact と fact の length）が含まれます。

この情報がそろったので、プロジェクトで connector を使う準備が整いました。

Security rules

外部 API integration にはすべて Security rules が必要です。これにより、integrations や特定 endpoint へのアクセスを認可するためのカスタムロジックを作成できます。このチュートリアルでは authentication と authorization は範囲外のため、catFacts integration へのすべてのアクセスを許可する security rule を作成します。

Tip

データを安全に保護する方法について詳しくは、Squid backend の security rules を参照してください。

Security rules は api-backend/src/service/example-service.ts にあります。SquidService クラスに decorator を追加することで、security rules を拡張できます。API integration 用の security rule を作成するには、INTEGRATION_ID（CONNECTOR_ID）をパラメータに取る @secureApi decorator を使用します。ExampleService クラスに新しい security rule を作成します。

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 を使用する

最後のステップは、Squid React SDK を使って React プロジェクト内で connector を利用することです。

セットアップ

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 を編集して、新しい connector を利用します。

Squid React SDK の squid.api().request() メソッドを使うと、API connector の endpoint を呼び出せます。request() メソッドは 3 つのパラメータを取ります。

integrationId: この connector は catFacts という名前にしました
endpointId: コンソールで API schema を検出（discover）した後、getRandomFact を使います
body object: 前述のとおり、request には max_length を含める必要があります

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

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

これで、App コンポーネント内からこのメソッドを呼び出せます。まず、connector が返す fact を追跡するための React state を作成します。request 関数を呼び出したら、新しい fact データで state を更新できます。request は promise を返すため、promise が解決された後にデータへアクセスするには .then を使う必要があります。React のテクニックとして、呼び出しを useEffect hook で包み、1 回だけ実行されるようにします。

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 フィールドにアクセスして、ページ上に 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 プロジェクトと backend の Squid プロジェクトの両方を起動する必要があります。

backend を実行するには、api-backend フォルダから次を実行します。

squid start

クライアントを実行するには、2 つ目のターミナルを開き、ルートフォルダから次を実行します。

npm run dev

これで、クライアントプロジェクトが http://localhost:PORT で動作しているのを確認できます。PORT はターミナルに表示されます。ページには fact と、その文字数（length）が表示されます。新しいランダムな猫の fact を表示するには、ページを更新してください。

おめでとうございます！たった数分で、Squid による最初の API integration のセットアップが完了しました。

次のステップ

Squid の API integrations の機能をさらに学ぶには、API の呼び出しに関する Client SDK ドキュメントを参照してください。HTTP API endpoint の security をカスタマイズする方法については、Backend SDK ドキュメントを参照してください。

Bonus: HTTP headers を組み込む

多くの場合、API integrations では secret を含む特別な headers が必要になります。Squid を使えば、コンソールでこれらの値をすばやく設定し、安全にアクセスして secured endpoint へ request を送れます。

これを示すために、request に API key が必要な別の cat facts API を使用します。この API には OpenAPI spec がないため、schema を手動で追加する手順もあわせて確認できます。

Random Cat Fact API にサブスクライブします。この API には $0 のサブスクリプションがあります。RapidAPI アカウントがない場合は作成する必要があります。サブスクライブすると、RapidAPI key を使って endpoint に接続できるようになります。
Squid Console で、新しい HTTP API integration を追加します。integration の ID は catFacts2 にします。
Add Connector をクリックします。この API には OpenAPI spec がないため、Open API spec の URL は空欄のままにします。
endpoint の base URL を指定します: https://random-cat-fact.p.rapidapi.com.
Add endpoint をクリックします。endpoint 名を catFact、relative path を / にします。HTTP method は GET です。
Add endpoint をクリックして endpoint を保存します。

この API には 2 つの header（X-RapidAPI-Key と X-RapidAPI-Host）が必要です。Squid Console で、これらを API schema に追加しましょう。

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

Add new field

Request 内の + をもう一度クリックし、X-RapidAPI-Host というフィールドを追加します。フィールドの location は HEADER です。

Headers in console

これらの headers をクライアントからの呼び出しに毎回追加する代わりに、Squid の injections 機能を使って、endpoint からのすべての API 呼び出しに特定フィールドを追加できるようにします。今回の呼び出しはすべて X-RapidAPI-Key と X-RapidAPI-Host headers を必要とするため、schema の Injections セクションに追加します。API key を安全に保つために、Squid Secrets を使用します。

Injections 内の + をクリックします。フィールド名を X-RapidAPI-Key にします。フィールドの location は HEADER を選択します。
Is this a secret value? を On に切り替えます。これにより、secret を選択するための dropdown が表示されます。
Select secret の dropdown で Create secret をクリックします。
Secret key として catFacts2 を入力します。
secret value には、Random Cat Fact API の RapidAPI ページから X-RapidAPI-Key の値をコピーします。これを secret の値として貼り付け、Save をクリックします。
注入（inject）するフィールドを保存するために Add field をクリックします。
Injections 内の + をもう一度クリックします。今度はフィールド名を X-RapidAPI-Host にします。フィールドの location は HEADER を選択します。
フィールドの値として random-cat-fact.p.rapidapi.com を入力し、Save をクリックします。

Injections in console

schema に加えたすべての変更を保存するために Save schema をクリックします。
Cat Facts アプリケーションの frontend 側で、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 backend 側で、2 つ目の decorator を追加して API へのアクセス認可機能を追加します。

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

backend で squid start、frontend で npm run dev を実行して、Cat Facts アプリの新バージョンを動かします。これで、アプリは secured API endpoint からデータへアクセスしています。

これで、schema injections と Squid Secrets を使って secured API endpoints にアクセスする方法が分かりました。Squid HTTP API integrations で利用できる機能の詳細は、API integration の呼び出しに関するドキュメントを参照してください。

Squid はあらゆる API と統合でき、複雑な移行を行わなくても、複数のデータソースで Squid の力を活用できます。​

TL;DR​

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

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

API Connector を作成する​

Connector を理解する​

Security rules​

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

セットアップ​

App.tsx​

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

次のステップ​

Bonus: HTTP headers を組み込む​