見出し画像

GPTsのActionsに実装する犬猫API

owlet_notes99.9

GPTsのActionsを使うと、外部APIからデータを取得できます。
実はつい最近まで「Schema（スキーマ）っ何？」と何もわかってない状態でした（今もなんとなくしか分かってません）。
犬や猫の写真を表示するAPI（The Dog APIとThe Cat API）を利用した例をネットでいくつか見つけ、参考にして使っていました。

ただこのAPIの使用例、ちょっとわからないことがあり、気になっていたので再度見直し整理しました。

DOG APIは2種類

犬種によるフィルターをかける場合、ドキュメントによるとAPIは2種類。
この2つを1つのActionsの中に設定します。

①犬種（breed）情報を取得

https://api.thedogapi.com//v1/breeds

/v1/breeds: 犬種情報を取得するためのエンドポイントと覚えておきます。成功した場合、犬種のリストを返します（下記参照）。
下記の「id」が犬種を指定する「breed_ids」に使う値。

（出力例）

[
    {
        "weight": {
            "imperial": "6 - 13",
            "metric": "3 - 6"
        },
        "height": {
            "imperial": "9 - 11.5",
            "metric": "23 - 29"
        },
        "id": 1,
        "name": "Affenpinscher",
        "bred_for": "Small rodent hunting, lapdog",
        "breed_group": "Toy",
        "life_span": "10 - 12 years",
        "temperament": "Stubborn, Curious, Playful, Adventurous, Active, Fun-loving",
        "origin": "Germany, France",
        "reference_image_id": "BJa4kxc4X"
    },
    {
        "weight": {
            "imperial": "50 - 60",
            "metric": "23 - 27"
        },
        "height": {
            "imperial": "25 - 27",
            "metric": "64 - 69"
        },
        "id": 2,
        "name": "Afghan Hound",
        "country_code": "AG",
        "bred_for": "Coursing and hunting",
        "breed_group": "Hound",
        "life_span": "10 - 13 years",
        "temperament": "Aloof, Clownish, Dignified, Independent, Happy",
        "origin": "Afghanistan, Iran, Pakistan",
        "reference_image_id": "hMyT4CDXR"
    },
    {
        "weight": {
            "imperial": "44 - 66",
            "metric": "20 - 30"
        },
        "height": {
            "imperial": "30",
            "metric": "76"
        },
        "id": 3,
        "name": "African Hunting Dog",
        "bred_for": "A wild pack animal",
        "life_span": "11 years",
        "temperament": "Wild, Hardworking, Dutiful",
        "origin": "",
        "reference_image_id": "rkiByec47"
    },

②犬種IDに基づいて画像検索

https://api.thecatapi.com/v1/images/search?breed_ids={breed.id}

/v1/images/search: 特定の犬種IDに基づいて画像を検索するためのエンドポイントと覚えておきます。上述したbreed_idsクエリパラメータによってフィルタリングされます。

各品種は、検索をフィルタリングするために使用することができますユニークな数字のID（breed_ids）を持っています。
なお、同仕様で猫のAPIがありますが、猫の場合breed_idsはユニークな4文字のIDです。

（出力例：https://api.thedogapi.com/v1/images/search?breed_ids=2）

[
    {
        "id": "zqTumVT7e",
        "url": "https://cdn2.thedogapi.com/images/zqTumVT7e.jpg",
        "width": 2457,
        "height": 2325
    }
]

なお、breed_ids=2はアフガンハウンドです

スキーマ設計

GPT CustomizerやActionsGPTに聞きながら整理しました。
スキーマは以下要素で構成されます。
なお、responsesがなくても動いたので、一旦外します。

  • openapi: APIのバージョンを指定します。この場合、3.1.0を使用しています。

  • info: APIの基本情報を提供します。タイトル、説明、バージョンを含みます。

  • servers: APIがホストされているサーバーのURLを指定します。犬種情報の取得と画像検索のための2つの基本URLがあります。

  • paths: APIの具体的なエンドポイントを定義します。

    • /v1/breeds: 犬種情報を取得するためのエンドポイントです。成功した場合、犬種のリストを返します。

    • /v1/images/search: 特定の犬種IDに基づいて画像を検索するためのエンドポイントです。breed_idsクエリパラメータによってフィルタリングされます。

  • responses: エンドポイントが呼び出された際の予想されるレスポンスを記述します。成功時（HTTP 200）のレスポンス形式を定義します。

  • parameters: エンドポイントに必要なパラメータを定義します。ここでは、breed_idsクエリパラメータが必須です。

スキーマです。
pathに/v1/breedsと/v1/images/searchの2つのエンドポイントを使っています。

{
  "openapi": "3.1.0",
  "info": {
    "title": "Dog Data API",
    "description": "Retrieve dog breeds information and their images from the API.",
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "https://api.thedogapi.com"
    }
  ],
  "paths": {
    "/v1/breeds": {
  "get": {
    "description": "Retrieve a list of dog breeds information. This endpoint does not require any parameters, allowing users to retrieve information on all available dog breeds without any filtering.",
    "operationId": "getDogBreeds",
    "parameters": []
  }
},
    "/v1/images/search": {
      "get": {
        "description": "Retrieve dog's images based on breed IDs.",
        "operationId": "GetDogImage",
        "parameters": [
          {
            "name": "breed_ids",
            "in": "query",
            "description": "The IDs of the breeds to filter the images.",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    }
  }
}

GPTsのActionsにセットします。

画面右のPreviewでテストします。

チャット中に表示される[debug] Calling HTTP endpointを見ると、breeds_idsに222をセットしてコールされています。

上述しましたが、本来スキーマにはresponseの記述も必要で、その部分を外しています。
responseにより、APIの利用者が特定のリクエストが成功した場合やエラーが発生した場合に、どのような応答が返されるかを事前に知ることができます。
以下のスキーマでは、/v1/breedsエンドポイントと/v1/images/searchエンドポイントについてそれぞれ、成功した場合のレスポンスの詳細を追記しています。

{
  "openapi": "3.1.0",
  "info": {
    "title": "Dog Data API",
    "description": "Retrieve dog breeds information and their images from the API.",
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "https://api.thedogapi.com"
    }
  ],
  "paths": {
    "/v1/breeds": {
      "get": {
        "description": "Retrieve a list of dog breeds information. This endpoint does not require any parameters, allowing users to retrieve information on all available dog breeds without any filtering.",
        "operationId": "getDogBreeds",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response with a list of all dog breeds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "Unique identifier for the dog breed."
                      },
                      "name": {
                        "type": "string",
                        "description": "Name of the dog breed."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/images/search": {
      "get": {
        "description": "Retrieve dog's images based on breed IDs.",
        "operationId": "GetDogImage",
        "parameters": [
          {
            "name": "breed_ids",
            "in": "query",
            "description": "The IDs of the breeds to filter the images.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with an array of images for the specified breed IDs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "URL of the image."
                      },
                      "breed_id": {
                        "type": "string",
                        "description": "Breed ID associated with the image."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

CAT APIも実装

猫のAPIも実装しました。
基本の仕様は犬のAPIと同じですが、breed_idsの型がstringなのが異なります（犬のbreed_idsはstringと設定しても読み込んでくれることもありました）。
スキーマです。

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cat Data API",
    "description": "Retrieve cat breeds information and their images from the API.",
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "https://api.thecatapi.com"
    }
  ],
  "paths": {
    "/v1/breeds": {
  "get": {
    "description": "Retrieve a list of cat breeds information. This endpoint does not require any parameters, allowing users to retrieve information on all available cat breeds without any filtering.",
    "operationId": "getCatBreeds",
    "parameters": []
  }
},
    "/v1/images/search": {
      "get": {
        "description": "Retrieve cat's images based on breed IDs.",
        "operationId": "GetCatImage",
        "parameters": [
          {
            "name": "breed_ids",
            "in": "query",
            "description": "The IDs of the breeds to filter the images.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  }
}

responseを追加したスキーマです。

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cat Data API",
    "description": "Retrieve cat breeds information and their images from the API.",
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "https://api.thecatapi.com"
    }
  ],
  "paths": {
    "/v1/breeds": {
      "get": {
        "description": "Retrieve a list of cat breeds information. This endpoint does not require any parameters, allowing users to retrieve information on all available cat breeds without any filtering.",
        "operationId": "getCatBreeds",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response with a list of all cat breeds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Unique identifier for the cat breed."
                      },
                      "name": {
                        "type": "string",
                        "description": "Name of the cat breed."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/images/search": {
      "get": {
        "description": "Retrieve cat's images based on breed IDs.",
        "operationId": "GetCatImage",
        "parameters": [
          {
            "name": "breed_ids",
            "in": "query",
            "description": "The IDs of the breeds to filter the images.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with an array of images for the specified breed IDs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "URL of the cat image."
                      },
                      "breed_id": {
                        "type": "string",
                        "description": "Breed ID associated with the image."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

犬と猫両方検索

犬と猫の両方のActionsを設定すると、一緒に画像を表示できます。
下が設定した状態です。
DALL•Eはたまに画像生成することがあったので外しています。
（チェックしておけば、見つからない場合写真の代わりに生成した画像で代用してくれることがあります）

犬と猫の両方の写真を探した例です。
（IDの型を勘違いするようで、うまく探してくれないこともありました）

この記事が気に入ったらサポートをしてみませんか？