Microsoft Graph コネクタ SDK のベスト プラクティス

  • [アーティクル]

この記事では、Microsoft Graph コネクタ SDK を使用してカスタム コネクタを実装するときに従うベスト プラクティスについて説明します。

クロールの進行状況マーカーの使用

クロールの進行状況マーカーは、プラットフォームによって最後に処理されたコネクタによって送信された特定のアイテムの識別子として機能します。 定期的な完全クロールと増分クロールの 2 種類を実装できます。

定期的なフル クロールでは、データ ソース内のすべての項目が取得され、インデックスに変更された項目または存在しない項目のみが取り込まれます。 項目が見つからない場合は、インデックスから削除されます。

増分クロールでは、最後の増分クロール以降に追加または変更されたアイテムが取得されます。 コネクタは、このクロールの一部として削除するアイテムを送信することもできます。 最初の増分クロールでは、最後のフル クロールの開始時刻も送信されます。 コネクタは必要に応じて、このクロールを使用して、最後のフル クロール後にのみ変更された項目をフェッチできます。

定期的な完全クロールと増分クロールの両方に、クロールの進行状況マーカーがあります。

定期的なフル クロール中のクロール進行状況マーカーの使用

以前のクロールがクラッシュした場合、または定期的なフル クロール中に Microsoft Graph コネクタ エージェントがオフラインになっているためにスケジュールされたクロールが見逃された場合、SDK はクロールの進行状況マーカーを送信します。

前のクロールがクラッシュしなかった場合は、最初からデータ ソースをクロールする必要があります。

増分クロール中のクロール進行状況マーカーの使用

1 つの増分クロール中に、コネクタはクロールの進行状況マーカーをコネクタ プラットフォームに送信し、次の増分クロールに対して引き続き実行されます。 コネクタは、このクロールを使用して、このマーカーの後に追加または変更された項目をフェッチできます。

ジェネリック型の構築

コンテンツ アイテムのプロパティ値には、データ型の範囲を指定できます。 gRPC にはジェネリック オブジェクトのコンストラクトがないため、SDK には、サポートされている任意のデータ型を保持できる GenericType 構造体が含まれています。 GenericType の構造は次のとおりです。

// Represents a generic type that can hold any supported value
message GenericType {
 // Value of the Generic type
 oneof value {
  // String type value
  string stringValue = 1;

  // Long value
  int64 intValue = 2;


  // Double value
  double doubleValue = 3;

  // DateTime value
  google.protobuf.Timestamp dateTimeValue = 4;

  // Boolean value
  bool boolValue = 5;

  // String collection value
  StringCollectionType stringCollectionValue = 6;

  // Long collection value
  IntCollectionType intCollectionValue = 7;

  // Double collection value
  DoubleCollectionType doubleCollectionValue = 8;

  // DateTime collection value
  TimestampCollectionType dateTimeCollectionValue = 9;
 }
}

// Collection of string
message StringCollectionType {
 // Value of string collection
 repeated string values = 1;
}

// Collection of long
message IntCollectionType {
 // Value of long collection
 repeated int64 values = 1;
}

// Collection of double
message DoubleCollectionType {
 // Value of double collection
 repeated double values = 1;
}

// Collection of DateTime
message TimestampCollectionType {
 // Value of DateTime collection
 repeated google.protobuf.Timestamp values = 1;
}

GenericType には、string、int64、double、DateTime、Boolean のいずれかの型、または文字列、int64、double、DateTime のコレクションのいずれかを指定できます。 これらの型を設定する方法の例を次に示します。

// Setting string value in generic type
    GenericType stringType = new GenericType
    {
        StringValue = "Hello"
    };

    // Setting int64 value in generic type
    GenericType int64Type = new GenericType
    {
        IntValue = 1000
    };

    // Setting double value in generic type
    GenericType doubleType = new GenericType
    {
        DoubleValue = 12.54
    };

    // Setting dateTime value in generic type
    GenericType dateTimeType = new GenericType
    {
        DateTimeValue = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(DateTime.UtcNow)
    };

    // Setting boolean value in generic type
    GenericType boolType = new GenericType
    {
        BoolValue = true
    };

    // Setting string collection value in generic type - Initialize the string collection first, add the values to the string collection and then set it in the generic type
    StringCollectionType stringCollection = new StringCollectionType();
    stringCollection.Values.Add("Value1");
    stringCollection.Values.Add("Value2");
    GenericType stringCollectionType = new GenericType
    {
        StringCollectionValue = stringCollection
    };

    // Setting int64 collection value in generic type - Initialize the int64 collection first, add the values to the int64 collection and then set it in the generic type
    IntCollectionType intCollection = new IntCollectionType();
    intCollection.Values.Add(1234);
    intCollection.Values.Add(5436);
    GenericType intCollectionType = new GenericType
    {
        IntCollectionValue = intCollection
    };

    // Setting double collection value in generic type - Initialize the double collection first, add the values to the double collection and then set it in the generic type
    DoubleCollectionType doubleCollection = new DoubleCollectionType();
    doubleCollection.Values.Add(12.54);
    doubleCollection.Values.Add(34.213);
    GenericType doubleCollectionType = new GenericType
    {
        DoubleCollectionValue = doubleCollection
    };

    // Setting datetime collection value in generic type - Initialize the datetime collection first, add the values to the datetime collection and then set it in the generic type
    TimestampCollectionType dateTimeCollection = new TimestampCollectionType();
    dateTimeCollection.Values.Add(Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(DateTime.UtcNow));
    dateTimeCollection.Values.Add(Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(DateTime.UtcNow.AddDays(-1)));
    GenericType dateTimeCollectionType = new GenericType
    {
        DateTimeCollectionValue = dateTimeCollection
    };

検索スキーマの構築

コネクタ スキーマには、次の制限があります。

  • プロパティ名: プロパティの名前は最大 32 文字で、英数字のみを使用できます。
  • Search注釈:
    • 検索できるのは、String 型または StringCollection 型のプロパティのみです。
    • String 型のプロパティにのみコンテンツ プロパティを指定できます。
    • コンテンツ プロパティは検索可能である必要があります。
    • コンテンツ プロパティをクエリ可能または取得可能にすることはできません。
    • リファイナブル プロパティは検索できません。
    • Refinable プロパティは、クエリ可能で取得可能である必要があります。
    • ブール型プロパティはリファインできません。
  • エイリアス: プロパティのエイリアスまたはフレンドリ名のセットは、最大 32 文字で、英数字のみを使用できます。

クロール中のアイテムのフェッチ

GetCrawlStream メソッドは、サーバー ストリーミング メソッドです。 クロール中に各アイテムをデータ ソースから CrawlStreamBit に変換し、応答ストリーム経由で送信します。

優れたスループットを得るには、コネクタがデータ ソースから項目のバッチを取得し、各項目を CrawlStreamBit に変換し、応答ストリーム経由で送信する必要があります。 バッチ サイズは、データ ソースによって異なります。 ストリーム上の項目の継続的なフローを維持するために、最適なサイズとして 25 を使用することをお勧めします。

コネクタ コードでの例外処理

gRPC 呼び出しからのすべての応答には、操作が成功したか失敗したか、失敗の理由、エラーがある場合の再試行の詳細を示す OperationStatus があります。 コード全体を try-catch ブロックにラップすることをお勧めします。 コネクタはすべての例外をログに記録し、適切な操作状態をプラットフォームに送信する必要があります。

接続管理フローは、Microsoft 365 管理センターに表示される StatusMessage で応答を送信します。 意味のあるメッセージを送信すると、ユーザー インターフェイスでエラーをデバッグしやすくなり、未処理の例外が残らないようにすることができます。

タイムアウト

ConnectionManagementService のすべてのメソッドが完了し、30 秒以内に戻る必要があります。それ以外の場合、プラットフォームは要求のタイムアウト エラー メッセージを返します。

コネクタからプラットフォームへのエラーの返送

すべての応答では、応答構造体で OperationStatus が使用されます。 エラーが発生した場合、コネクタは OperationStatus を 使用してエラーの理由を送信し、情報をプラットフォームに再試行する必要があります。 OperationStatus を使用して、データ ソースにアクセスするための有効期限が切れた資格情報などの接続レベルのエラーが発生した場合に、クロール中にエラーを設定します。

OperationStatus 構造体には、エラーを表すために使用できる 3 つのフィールドがあります。

OperationResult

OperationResult は、エラーの理由を保持できる列挙体です。

StatusMessage

StatusMessage は OperationStatus のプロパティで、カスタム メッセージを格納して、接続のセットアップ中に管理者に表示されるエラー理由を表示できます。 たとえば、 ValidateAuthentication メソッドを使用した検証中に資格情報が正しくない場合、 結果 プロパティを AuthenticationIssue に設定し、 statusMessage プロパティを 指定した資格情報を不正に設定できます。 ValidateAuthentication メソッドが呼び出されると、この statusMessage が検索管理者に表示されます。クロール中に、このシナリオは接続を失敗状態に移動し、認証エラーを管理者に表示し、管理者に資格情報を更新してデータ ソースにアクセスするように求めます。

RetryDetails

RetryDetails を使用すると、コネクタはクロール中の一時的なエラーに関する情報をプラットフォームに再送信し、それを使用して操作を繰り返すことができます。

再試行には、標準バックオフまたは指数バックオフを指定できます。 コネクタは、一時停止時間、バックオフ率、バックオフ係数を設定し、それらを送信できます。 たとえば、クロール中にデータ ソースが調整された場合、コネクタは OperationResult を DatasourceError に設定し、データ ソースからの応答ヘッダーの retry-header に従って再試行の詳細を送信できます。

OperationResult のエラー マッピング

次のエラーは、接続を失敗状態に移動します。

  • OperationResult.AuthenticationIssue

  • OperationResult.ValidationFailure

その他の操作コードは一時的なエラーとして扱われ、後続のクロールで再試行されます。

関連コンテンツ