GraphQL API のインポート

GraphQL は、API 用のオープンソースの業界標準クエリ言語です。 GraphQL API は、リソースに対するアクションを中心に設計されたエンドポイントベース (または REST スタイル) の API とは異なり、より広範な一連のユース ケースをサポートし、データ型、スキーマ、クエリに重点を置いています。

API Managementを使用して GraphQL API を公開すると、次のことが可能になります。

• Azure portal、Azure CLI、またはその他の Azure ツールを使用して、GraphQL エンドポイントまたは GraphQL スキーマを API として追加します。
• (プレビュー) GraphQL スキーマで定義されたフィールドに対して HTTP リゾルバーを使用して、REST API または SOAP API の情報を使用して GraphQL API を拡張または設計します。
• GraphQL 固有の攻撃をセキュリティで保護するために、既存のアクセス制御ポリシーと GraphQL 検証ポリシーの両方を適用することで、GraphQL API をセキュリティで保護します。
• スキーマを調べ、Azure と開発者ポータルで GraphQL API に対してテスト クエリを実行する。

注意

• API Management の 1 つの GraphQL API は、1 つの GraphQL バックエンド エンドポイントにマップできます。
• GraphQL API には、既存の GraphQL エンドポイントからの GraphQL スキーマ、またはユーザーがアップロードした GraphQL スキーマが必要です。
• API Management では、GraphQL スキーマ内でのクエリ、変更、およびサブスクリプション操作の種類がサポートされます。
• サブスクリプションは、従量課金サービス レベルではサポートされていません。
• サブスクリプションは、graphql-ws WebSocket プロトコルを使用して実装する必要があります。 クエリと変更は、WebSocket ではサポートされていません。

この記事では、次のことを行います。

• GraphQL API を使用する利点の詳細を確認します。
• API Management インスタンスに GraphQL API を追加します。
• GraphQL API をテストします。
• API Management での GraphQL API の制限事項について確認します。

GraphQL スキーマをインポートし、REST または SOAP API エンドポイントを使用してフィールド リゾルバーを設定する場合は、「GraphQL スキーマをインポートし、フィールド リゾルバーを設定する」を参照してください。

前提条件

• 既存の API Management インスタンスがある。 まだない場合は、作成してください。

• GraphQL API。

• Azure CLI

  • Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。

    

  • CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

    • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

    • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

    • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

• Azure PowerShell

  • Azure PowerShell をローカルで使用する場合は、次のようにします。
    • Az PowerShell モジュールをインストールします。
    • Connect-AzAccount コマンドレットを使用して、Azure アカウントに接続します。
  • Azure Cloud Shell を使用する場合は、次のようにします。
    • 詳細については、Azure Cloud Shell の概要に関するページを参照してください。

GraphQL API を追加する

ポータル

1. Azure portal で、API Management インスタンスに移動します。

2. 左側のメニューで、 [API]>[+ API の追加] を選択します。

3. [Define a new API](新しい API の定義) で、GraphQL アイコンを選びます。

   

4. ダイアログ ボックスで [完全] を選択し、必要なフォーム フィールドを入力します。

   

   フィールド	説明
   [表示名]	GraphQL API を表示するときに使用する名前。
   名前	GraphQL API の未加工の名前。 表示名を入力すると自動的に設定されます。
   GraphQL API エンドポイント	ベース URL と GraphQL API のエンドポイント名。 (例: https://example.com/your-GraphQL-name)。 https://swapi-graphql.azure-api.net/graphql などの一般的な "Star Wars" GraphQL エンドポイントをデモとして使用することもできます。
   スキーマのアップロード	必要に応じて、スキーマ ファイルを参照してアップロードし、GraphQL エンドポイントから取得したスキーマを置き換えます (使用可能な場合)。
   説明	API の説明を追加します。
   URL スキーム	[HTTP]、[HTTPS]、または [両方] を選択します。 既定の選択は 両方 です。
   API URL サフィックス	この API Management インスタンスでこの特定の API を識別するための URL サフィックスを追加します。 この API Management インスタンス内で一意である必要があります。
   ベース URL	API ベース URL を表示する編集できないフィールド
   タグ	GraphQL API を新規または既存のタグに関連付けます。
   製品	GraphQL API を製品に関連付けて発行します。
   ゲートウェイ	GraphQL API を既存のゲートウェイに関連付けます。 既定のゲートウェイの選択: マネージド。
   この API をバージョン管理しますか?	GraphQL API にバージョン管理スキームを適用する場合に選択します。

5. ［作成］ を選択します

6. API が作成されたら、[デザイン] タブの [フロントエンド] セクションでスキーマを参照します。

Azure CLI

次の例では、 az apim api import コマンドを使用して、指定した URL から apim-hello-worldという名前の API Management インスタンスに GraphQL パススルー API をインポートします。

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --display-name $DisplayName --specification-format $SpecificationFormat --specification-url $SpecificationURL

API をインポートした後、必要に応じて、 az apim api update コマンドを使用して設定を更新できます。

PowerShell

次の例では、 Import-AzApiManagementApi Azure PowerShell コマンドレットを使用して、指定した URL から apim-hello-worldという名前の API Management インスタンスに GraphQL パススルー API をインポートします。

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

API をインポートした後、必要に応じて Set-AzApiManagementApi コマンドレットを使用して設定を更新できます。

GraphQL API をテストする

1. API Management インスタンスに移動します。

2. サイド ナビゲーション メニューの [API] セクションで、 [API] を選択します。

3. [すべての API] の下で、使用する GraphQL API を選択します。

4. [テスト] タブを選択して、テスト コンソールにアクセスします。

5. [ヘッダー] で、次のようにします。

   1. [名前] ドロップダウン メニューからヘッダーを選びます。
   2. [値] フィールドに値を入力します。
   3. ヘッダーをさらに追加するには、 [+ ヘッダーの追加] を選びます。
   4. ヘッダーを削除するには、ごみ箱アイコンを使用します。

6. GraphQL API に製品を追加した場合は、 [Apply product scope](製品スコープの適用) で製品スコープを適用します。

7. [クエリ エディター] で、以下のいずれかを行います。

   1. サイド メニューの一覧から、少なくとも 1 つのフィールドまたはサブフィールドを選択します。 選択したフィールドとサブフィールドがクエリ エディターに表示されます。

   2. クエリ エディターで入力を開始して、クエリを作成します。

      

8. [クエリ変数] で、{2}同じクエリまたは変更を再利用し、異なる値を渡す変数を追加します。

9. [Send] を選択します。

10. [応答] を表示します。

    

11. 前の手順を繰り返して、さまざまなペイロードをテストします。

12. テストが完了したら、テスト コンソールを終了します。

注意

テスト コンソールでサブスクリプションをテストできます:

• クエリ エディターでサブスクリプション クエリを設定し、[接続] を選択してバックエンド サービスへの WebSocket 接続を確立します。
• [サブスクリプション] ペインで接続の詳細を確認します。
• WebSocket 接続は、切断するか、新しい WebSocket サブスクリプションに接続するまで維持されます。

関連トピック

• API のインポートの制限事項
• OpenAPI 仕様のインポート
• SOAP API のインポート
• SOAP API のインポートと REST への変換
• App Service API をインポートする
• コンテナー アプリ API をインポートする
• Websocket API のインポート
• GraphQL API のインポート
• GraphQL スキーマをインポートし、フィールド リゾルバーを設定する
• Azure 関数アプリをインポートする
• Azure ロジック アプリをインポートする
• Service Fabric サービスをインポートする
• SAP OData メタデータをインポートする
• API の編集

次のステップ

公開された API の変換と保護