フェデレーションホットチョコレート

このパッケージは現在正式に非推奨となり、HotChocolate 組み込みフェデレーション モジュールが優先されます。

このパッケージは、Federation v2 に対する組み込み HC サポートがなかったときに作成されましたが、HC v13.9.0 以降、 HotChocolate.ApolloFederationパッケージは Federation v2 を完全にサポートするようになりました。 HC エコシステムでの統合を簡素化するために、完全な機能を備えた単一の組み込みパッケージをサポートすることを優先し、このパッケージを非推奨にすることを決定しました。

アポロフェデレーションのホットチョコレート

警告パブリック API に対する重大な変更のため、代替 API (現在作業中) が完了するまで、新しいバージョンのHotChocolateをサポートできません。当社がサポートできるのは、v 13.5.xおよび v 13.6.xリリースのみです。

Apollo Federation は、複数の GraphQL API を組み合わせた統合スーパーグラフの作成に役立つ強力なオープン アーキテクチャです。 ApolloGraphQL.HotChocolate.Federation HotChocolateエコシステムでサブグラフを構築するための Apollo Federation サポートを提供します。個々のサブグラフは互いに独立して実行できますが、Federated ディレクティブを使用して他のサブグラフとの関係を指定することもできます。詳細については、Apollo Federation のドキュメントを参照してください。

インストール

ApolloGraphQL.HotChocolate.Federationパッケージが Nuget に公開されます。次のパッケージ参照を使用して.csprojファイルを更新します。

">

  < ItemGroup >
    
    < PackageReference Include = " HotChocolate.AspNetCore " Version = " 13.6.0 " />
    
    < PackageReference Include = " ApolloGraphQL.HotChocolate.Federation " Version = " $LatestVersion " />
  ItemGroup >

必要なパッケージをインストールした後、Apollo Federation を GraphQL サービスに登録する必要があります。

 var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( ) 
    // register your types and services
    ;

var app = builder . Build ( ) ;
app . MapGraphQL ( ) ;
app . Run ( ) ;

Federation v1 スキーマにオプトインしたい場合は、代わりに.AddApolloFederation()拡張機能を使用する必要があります。

使用法

GraphQL スキーマの作成方法とサーバーの構成方法の詳細については、 HotChocolateドキュメントを参照してください。

Apollo Federation では、サブグラフがスーパーグラフを認識できるようにするために、追加のメタデータを提供する必要があります。エンティティは、指定された@keyによってスーパーグラフ全体で一意に識別できる GraphQL オブジェクトです。エンティティはさまざまなサブグラフによって拡張できるため、エンティティにアクセスするための追加のエントリ ポイントが必要です。つまり、サブグラフはサポートするエンティティの参照リゾルバを実装する必要があります。

フェデレーションの詳細については、Apollo のドキュメントを参照してください。

注釈

すべてのフェデレーション ディレクティブは、クラス/フィールド/メソッドに直接適用できる属性として提供されます。

productRepository.GetById(id); }">

 [ Key ( " id " ) ]
public class Product
{
    public Product ( string id , string name , string ? description )
    {
        Id = id ;
        Name = name ;
        Description = description ;
    }

    [ ID ]
    public string Id { get ; }

    public string Name { get ; }

    public string ? Description { get ; }

    // assumes ProductRepository with GetById method exists
    // reference resolver method must be public static
    [ ReferenceResolver ]
    public static Product GetByIdAsync (
        string id ,
        ProductRepository productRepository )
        => productRepository . GetById ( id ) ;
}

これにより、次のタイプが生成されます

 type Product @key ( fields : " id " ) {
    id : ID !
    name : String !
    description : String
}

フェデレーションの属性

フェデレーション v1 ディレクティブ

• オブジェクトに適用できるExtends 。 @extendsドキュメントを参照してください。
• Externalフィールドに適用されます。 @externalドキュメントを参照してください。
• オブジェクトに適用できるKey 。 @keyドキュメントを参照してください。
• フィールドに適用可能なProvides 。 @providesドキュメントを参照してください。
• フィールドに適用されるRequires 、 @requiresドキュメントを参照してください。

フェデレーション v2 ディレクティブ (すべての v1 ディレクティブを含む)

• スキーマに適用できるApolloTagについては、 @tagドキュメントを参照してください。
• ApolloAuthenticated (v2.5 以降)列挙型、フィールド、インターフェイス、オブジェクトに適用可能、 @authenticatedドキュメント
• ComposeDirective (v2.1 以降)はスキーマに適用可能です。 @composeDirectiveドキュメントを参照してください。
• スキーマに適用可能なContact 。 @contactの使用法を参照してください。
• Inaccessibleすべての型定義に適用されます。 @inaccessibleドキュメントを参照してください。
• InterfaceObject (v2.3 以降)オブジェクトに適用可能、 @interfaceObjectドキュメントを参照
• KeyInterfaceインターフェイスに適用できます。エンティティ インターフェイス@keyドキュメントを参照してください。
• スキーマに適用可能なLink 。 @linkドキュメントを参照してください。
• RequiresScopes (v2.5 以降)は列挙型、フィールド、インターフェイス、オブジェクトに適用可能、 @requiresScopesドキュメント
• スキーマに適用可能Shareable 。 @shareableドキュメントを参照

エンティティの解決

• エンティティ リゾルバー メソッド パラメーターに適用できるMapにより、複雑な引数をより単純な表現値 (例: [Map("foo.bar")] string barマップできます)
• ReferenceResolverエンティティ クラス内のパブリック静的メソッドに適用され、エンティティ リゾルバーを示します。

コードファースト

あるいは、より詳細な制御が必要な場合は、コードファーストアプローチを使用して、基礎となる GraphQL 型記述子にフェデレーション情報を手動で入力できます。すべてのフェデレーション ディレクティブは、該当する記述子で対応するメソッドを公開します。

GetProduct(default!, default!)); } private static Product GetProduct( string id, ProductRepository productRepository) => productRepository.GetById(upc); }">

 public class Product
{
    public Product ( string id , string name , string ? description )
    {
        Id = id ;
        Name = name ;
        Description = description ;
    }

    [ ID ]
    public string Id { get ; }

    public string Name { get ; }

    public string ? Description { get ; }
}

public class ProductType : ObjectType < Product >
{
    protected override void Configure ( IObjectTypeDescriptor < Product > descriptor )
    {
        descriptor
            . Key ( " id " )
            . ResolveReferenceWith ( t => GetProduct ( default ! , default ! ) ) ;
    }

    private static Product GetProduct (
        string id ,
        ProductRepository productRepository )
        => productRepository . GetById ( upc ) ;
}

これにより、次のタイプが生成されます

 type Product @key ( fields : " id " ) {
    id : ID !
    name : String !
    description : String
}

記述子の拡張子

フェデレーション v1 ディレクティブ

• オブジェクトに適用できるExtendsTypeについては、 @extendsドキュメントを参照してください。
• Externalフィールドに適用されます。 @externalドキュメントを参照してください。
• オブジェクトに適用できるKey(fieldset) 。 @keyドキュメントを参照してください。
• フィールドに適用できるProvides(fieldset) 。 @providesドキュメントを参照してください。
• フィールドに適用できるRequires(fieldset)については、 @requiresドキュメントを参照してください。

フェデレーション v2 ディレクティブ (すべての v1 ディレクティブを含む)

• ApolloTagすべての型定義に適用できます。 @tagドキュメントを参照してください。
• ApolloAuthenticated (v2.5 以降)列挙型、フィールド、インターフェイス、オブジェクトに適用可能、 @authenticatedドキュメント
• ComposeDirective(name) (v2.1 以降)スキーマに適用可能、 @composeDirectiveドキュメントを参照
• Contact(name, url?, description?)スキーマに適用されます。 @contact使用法を参照してください。
• Inaccessibleすべての型定義に適用されます。 @inaccessibleドキュメントを参照してください。
• InterfaceObject (v2.3 以降)オブジェクトに適用可能、 @interfaceObjectドキュメントを参照
• オブジェクトに適用できるKey(fieldset) 。 @keyドキュメントを参照してください。
• Link(url, [import]?)スキーマに適用できます。 @linkドキュメントを参照してください。
• NonResolvableKey(fieldset)オブジェクトに適用できます。非解決@keyのドキュメントを参照してください。
• RequiresScopes(scopes) (v2.5 以降)列挙型、フィールド、インターフェイス、オブジェクトに適用可能、 @requiresScopesドキュメント
• Shareableフィールドとオブジェクトに適用できます。 @shareableドキュメントを参照してください。

エンティティの解決

• エンティティを解決できるようにするには、 ResolveReferenceWith関数を提供する必要があります

高度な使用例

ビルド時にスキーマを生成する

コマンド ライン インターフェイスのサーバー サポートの詳細については、HotChocolate のドキュメントを参照してください。ビルド時にスキーマを生成するには、 HotChocolate.AspNetCore.CommandLineパッケージに依存関係を追加し、 RunWithGraphQLCommandsを許可するようにサーバーを構成する必要があります。

 var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( )
    // register your types and services
    ;

var app = builder . Build ( ) ;
app . MapGraphQL ( ) ;
app . RunWithGraphQLCommands ( args ) ;

次に、次を実行してスキーマを生成できます。

dotnet run -- schema export --output schema.graphql

フェデレーションバージョンの指定

デフォルトでは、 ApolloGraphQL.HotChocolate.Federationサポートされている最新のフェデレーション バージョンを使用してスキーマを生成します。古いバージョンの使用をオプトインしたい場合は、 AddApolloFederationV2拡張機能を構成するときにバージョンを指定することで、そのようにすることができます。

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( FederationVersion . FEDERATION_23 )
    // register your types and services
    ;

あるいは、特定のフェデレーション バージョンを対象とするカスタムFederatedSchemaを提供することもできます。

 public class CustomSchema : FederatedSchema
{
    public CustomSchema ( ) : base ( FederationVersion . FEDERATION_23 ) {
    }
}

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( new CustomSchema ( ) )
    // register your types and services
    ;

スキーマのカスタマイズ

いくつかのディレクティブを適用してスキーマをカスタマイズしたい場合は、 SchemaTypeDescriptorAttribute拡張する属性で注釈を付けることができるカスタムFederatedSchemaを提供することもできます。

 [ AttributeUsage ( AttributeTargets . Class | AttributeTargets . Struct , Inherited = true , AllowMultiple = true ) ]
public sealed class CustomAttribute : SchemaTypeDescriptorAttribute
{
    public override void OnConfigure ( IDescriptorContext context , ISchemaTypeDescriptor descriptor , Type type )
    {
        // configure your directive here
    }
}

[ Custom ]
public class CustomSchema : FederatedSchema
{
    public CustomSchema ( ) : base ( FederationVersion . FEDERATION_23 ) {
    }
}

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( new CustomSchema ( ) )
    // register your types and services
    ;

あるいは、フェデレーテッド・サブグラフを構築するときにカスタム・スキーマ構成アクションを指定することもできます。

 var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( schemaConfiguration : s =>
    {
        // apply your directive here
    } )
    // register your types and services
    ; 

解決できない@key

サブグラフは、エンティティにフィールドを提供せずに、フィールドの戻り値の型としてエンティティを使用できます。有効なスキーマを生成するには型定義が必要なため、 [NonResolvableKeyAttribute]を使用してスタブオブジェクトを定義できます。

 public class Review {
    public Review ( Product product , int score )
    {
        Product = product ;
        Score = score
    }

    public Product Product { get ; }
    public int Score { get ; }
}


[ NonResolvableKey ( " id " ) ]
public class Product {
    public Product ( string id )
    {
        Id = id ;
    }

    public string Id { get ; }
} 

@composedDirective使用法

デフォルトでは、Supergraph スキーマはすべてのカスタム ディレクティブを除外します。 @composeDirectiveは、Supergraph スキーマに保存する必要があるカスタム ディレクティブを指定するために使用されます。

ApolloGraphQL.HotChocolate.Federation Apollo Federation v2 @link定義を自動的に適用する共通のFederatedSchemaクラスを提供します。カスタム スキーマ ディレクティブを適用する場合は、このクラスを拡張し、必要な属性/ディレクティブを追加する必要があります。

@composedDirective適用するときは、仕様に@link必要もあります。その後、カスタム スキーマをAddApolloFederationV2拡張機能に渡す必要があります。

 [ ComposeDirective ( " @custom " ) ]
[ Link ( " https://myspecs.dev/myCustomDirective/v1.0 " , new string [ ] { " @custom " } ) ]
public class CustomSchema : FederatedSchema
{
}

var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( new CustomSchema ( ) )
    // register your types and services
    ;

あるいは、構成アクションを使用して@composedDirectiveをターゲット スキーマに直接適用することもできます。

 var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( schemaConfiguration : s =>
    {
        s . Link ( " https://myspecs.dev/myCustomDirective/v1.0 " , new string [ ] { " @custom " } ) ;
        s . ComposeDirective ( " @custom " ) ;
    } )
    // register your types and services
    ; 

@interfaceObject使用法

Apollo Federation v2 は、エンティティ インターフェイスをサポートしています。これは、GraphQL インターフェイスの強力な拡張機能であり、すべての実装型を実装する (または意識することなく) 必要なく、スーパーグラフ全体にわたってインターフェイスの機能を拡張できます。

インターフェイスを定義するサブグラフでは@key適用する必要があります

 [ InterfaceType ]
[ KeyInterface ( " id " ) ]
public interface Product
{
    [ ID ]
    string Id { get ; }

    string Name { get ; }
}

[ Key ( " id " ) ]
public class Book : Product
{
    [ ID ]
    public string Id { get ; set ; }

    public string Name { get ; set ; }

    public string Content { get ; set ; }
}

次に、インターフェイスを型にして、 @interfaceObjectと同じ@keyディレクティブを適用することで、別のサブグラフでインターフェイスを拡張できます。これにより、インターフェイスを実装するすべてのエンティティに新しいフィールドを追加できます (たとえば、すべてのProduct実装にReviewsフィールドを追加するなど)。

Reviews { get; set; } }">

 [ Key ( " id " ) ]
[ InterfaceObject ]
public class Product
{
    [ ID ]
    public string Id { get ; set ; }

    public List < string > Reviews { get ; set ; }
} 

@requiresScopes によるアクセス制御

@requiresScopesディレクティブは、適切な JWT スコープを持つ認証されたスーパーグラフ ユーザーのみがターゲット要素にアクセスできることを示すために使用されます。詳細については、Apollo Router の記事を参照してください。

repository.Products.FirstOrDefault(t => t.Id.Equals(id)); }">

 public class Query
{
    [ RequiresScopes ( scopes : new string [ ] { " scope1, scope2 " , " scope3 " } ) ]
    [ RequiresScopes ( scopes : new string [ ] { " scope4 " } ) ]
    public Product ? GetProduct ( [ ID ] string id , Data repository )
        => repository . Products . FirstOrDefault ( t => t . Id . Equals ( id ) ) ;
}

これにより、次のスキーマが生成されます

 type Query {
    product ( id : ID ! ): Product @requiresScopes ( scopes : [ [ " scope1, scope2 " , " scope3 " ], [ " scope4 " ] ])
}

サブグラフの連絡先情報の提供

@contactディレクティブを使用して、チームの連絡先情報をサブグラフ スキーマに追加できます。この情報は Studio に表示され、他のチームがサブグラフに関するサポートを求める連絡先を知るのに役立ちます。詳細についてはドキュメントを参照してください。

スキーマに[Contact]属性を適用する必要があります。カスタム スキーマに[Contact]属性を適用して、カスタム スキーマをAddApolloFederationV2拡張機能に渡すことができます。

(); .AddApolloFederationV2(new CustomSchema()) // register your types and services ;">

 [ Contact ( " MyTeamName " , " https://myteam.slack.com/archives/teams-chat-room-url " , " send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall) " ) ]
public class CustomSchema : FederatedSchema
{
}

var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddType < ContactDirectiveType > ( ) ;
    . AddApolloFederationV2 ( new CustomSchema ( ) )
    // register your types and services
    ;

または、カスタム スキーマ構成アクションを提供して@contactディレクティブをスキーマに直接適用します

 var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services
    . AddGraphQLServer ( )
    . AddApolloFederationV2 ( schemaConfiguration : s =>
    {
        s . Contact ( " MyTeamName " , " https://myteam.slack.com/archives/teams-chat-room-url " , " send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall) " ) ;
    } )
    // register your types and services
    ; 

カスタムクエリタイプ

ApolloGraphQL.HotChocolate.Federation自動的にデフォルトでQueryタイプ名を使用します。カスタム ルートQuery操作タイプを使用する場合は、それらのカスタム値を使用してスキーマを明示的に構成する必要があります。

() // register your other types and services ; var app = builder.Build(); app.MapGraphQL(); app.Run();">

 public class CustomQuery
{
    public Foo ? GetFoo ( [ ID ] string id , Data repository )
        => repository . Foos . FirstOrDefault ( t => t . Id . Equals ( id ) ) ;
}

var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services
    . AddGraphQLServer ( )
    . ModifyOptions ( opts => opts . QueryTypeName = " CustomQuery " )
    . AddApolloFederationV2 ( )
    . AddQueryType < CustomQuery > ( )
    // register your other types and services
    ;

var app = builder . Build ( ) ;
app . MapGraphQL ( ) ;
app . Run ( ) ;

移行ガイド

HotChocolate.FederationからApolloGraphQL.HotChocolate.Federationへの移行は簡単です。新しいモジュールを指すようにパッケージのインポートを更新するだけです

- + ">

  
    
    
    
-    
+    
  

名前空間のインポートを更新します

 - using HotChocolate.ApolloFederation;
+ using ApolloGraphQL.HotChocolate.Federation;

移行プロセスを可能な限りシームレスにしようとしましたが、ライブラリにいくつかの調整を加える必要がありました。一部の内部 API に依存しているため、ライブラリに次のような重大な変更を加える必要がありました。

• [Key]クラスにのみ適用できるようになり、個々のフィールドには適用できなくなりました
• [ReferenceResolver] 、エンティティ内のパブリック静的メソッドにのみ適用できるようになり、クラスには適用できなくなりました。

既知の制限事項

エンティティ リゾルバーの自動マップのみのスカラー値

[EntityResolver]は、サポートされている@key / @requires値にエンティティ表現を自動的にマッピングできます。スカラー@keyフィールドは自動的にマッピングされ、 [Map]属性を使用して複雑な選択セットからスカラー値を自動マッピングできます。

現在、リスト値とオブジェクト値の自動マッピングはサポートされていません。

回避策として、実装内の表現オブジェクトを手動で解析する必要があります。

 [ ReferenceResolver ]
public static Foo GetByFooBar (
    [ LocalState ] ObjectValueNode data
    Data repository )
{
    // TODO implement logic here by manually reading values from local state data
} 

限定的な@linkサポート

現在、参照されるサブグラフからの要素のインポートのみがサポートされています。

要素の名前空間と名前変更は現在サポートされていません。詳細については、問題を参照してください。

接触

ライブラリまたはコードについて具体的な質問がある場合は、Apollo コミュニティ フォーラムでディスカッションを開始するか、Discord サーバーで会話を開始してください。

貢献する

まず、リポジトリをフォークし、新しいブランチをチェックアウトしてください。次に、次を実行してライブラリをローカルに構築できます。

 # install dependencies
dotnet restore
# build project
dotnet build
# run tests
dotnet test

詳細については、CONTRIBUTING.md を参照してください。

ローカルブランチを設定したら、未解決の問題を参照して、どこに貢献できるかを確認してください。

安全

セキュリティの問題についてチームに連絡する方法の詳細については、セキュリティ ポリシーを参照してください。

ライセンス

このライブラリは、MIT ライセンス (MIT) に基づいてライセンスされています。