Рекомендации по пакету SDK для соединителей Microsoft Graph

  • Статья

В этой статье приведены рекомендации по использованию пакета SDK соединителей Microsoft Graph для реализации пользовательского соединителя.

Использование маркера хода выполнения обхода контента

Маркер выполнения обхода контента выступает в качестве идентификатора для конкретного элемента, отправленного соединителем, который последний раз обрабатывался платформой. Можно реализовать два типа обхода контента: периодическое полное и добавочное.

Периодические полные обходы контента получают все элементы в источнике данных и получают только те элементы, которые изменены или отсутствуют в индексе. Если элемент не находится, он удаляет его из индекса.

При добавочном обходе элементы добавляются или изменяются с момента последнего добавочного обхода. Соединитель также может отправлять элементы для удаления в рамках этого обхода. При первом добавочном обходе также отправляется время начала последнего полного обхода контента. Соединитель может при необходимости использовать этот обход для получения элементов, измененных только после последнего полного обхода.

Периодические полные и добавочные обходы контента имеют маркеры хода обхода контента.

Использование маркера хода обхода во время периодического полного обхода контента

Пакет SDK отправляет маркер хода обхода, если предыдущий обход контента завершился сбоем или запланированный обход контента был пропущен из-за того, что агент соединителя Microsoft Graph находится в автономном режиме во время периодического полного обхода контента.

Если предыдущее сканирование не завершалось сбоем, необходимо выполнить обход источника данных с самого начала.

Использование маркера выполнения обхода при добавочном обходе контента

Во время одного добавочного обхода соединитель отправляет маркер хода обхода на платформу соединителя, и он будет продолжать делать это для следующего добавочного обхода. Соединитель может использовать этот обход для получения добавленных или измененных элементов после этого маркера.

Создание универсальных типов

Значения свойств элемента контента могут иметь диапазон типов данных. Поскольку 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 символов, и допускаются только буквенно-цифровые символы.
  • заметки Поиск:
    • Доступны только свойства типа String или StringCollection .
    • Свойством содержимого могут быть только свойства типа String .
    • Свойства контента должны быть доступны для поиска.
    • Свойства содержимого не могут быть запрашиваемыми или извлекаемыми.
    • Уточненное свойство не должно быть доступны для поиска.
    • Уточненное свойство должно быть запрашиваемым и извлекаемым.
    • Логические свойства не могут быть уточнены.
  • Псевдонимы. Набор псевдонимов или понятное имя свойства может содержать не более 32 символов и только буквенно-цифровые символы.

Получение элементов во время обхода контента

Метод GetCrawlStream является методом потоковой передачи сервера. Он преобразует каждый элемент из источника данных в CrawlStreamBit во время обхода и отправляет его через поток ответа.

Чтобы получить хорошую пропускную способность, соединитель должен получить пакет элементов из источника данных, преобразовать каждый элемент в CrawlStreamBit и отправить их через поток ответа. Размер пакета зависит от источника данных. Рекомендуется 25 в качестве оптимального размера для поддержания непрерывного потока элементов по потоку.

Обработка исключений в коде соединителя

Все ответы от вызовов gRPC имеют значение OperationStatus , указывающее, была ли операция успешной или неудачной, причину сбоя и сведения о повторных попытках при наличии сбоев. Мы рекомендуем упаковать весь код в блок try-catch. Соединитель должен регистрировать все исключения и отправлять на платформу надлежащее состояние операции.

Потоки управления подключениями отправляют ответ с параметром StatusMessage, который отображается в Центр администрирования Microsoft 365. Отправка значимых сообщений упрощает отладку ошибок в пользовательском интерфейсе и не оставляет необработанных исключений.

Время ожидания

Все методы в ConnectionManagementService должны завершиться и вернуться в течение 30 секунд; В противном случае платформа вернет сообщение об ошибке времени ожидания для запроса.

Отправка ошибок обратно из соединителя на платформу

Все ответы используют OperationStatus в структуре ответа. При возникновении каких-либо ошибок соединители должны использовать OperationStatus для отправки причины сбоя и повторных попыток обратно на платформу. Используйте OperationStatus , чтобы задать ошибки во время обхода контента, если возникают ошибки уровня подключения, такие как истекшие учетные данные для доступа к источнику данных.

Структура OperationStatus содержит три поля, которые можно использовать для представления любых ошибок.

OperationResult

OperationResult — это перечисление, которое может содержать причину сбоя.

StatusMessage

StatusMessage — это свойство OperationStatus , которое может хранить пользовательское сообщение для отображения причины сбоя, которая будет отображаться администратору во время настройки подключения. Например, если учетные данные неверны во время проверки с помощью метода ValidateAuthentication , свойству result можно задать значение AuthenticationIssue , а свойству statusMessage — значение Неверные учетные данные. При вызове метода ValidateAuthentication этот параметр statusMessage будет отображаться администратору поиска. Во время обхода этот сценарий переместит подключение в состояние сбоя, отобразит ошибку проверки подлинности для администратора и предложит администратору обновить учетные данные для доступа к источнику данных.

RetryDetails

RetryDetails позволяет соединителю повторно отправлять на платформу сведения о временных ошибках во время обхода контента и использовать его для повторения операции.

Повторная попытка может быть стандартной или экспоненциальной. Соединитель может задать время паузы, частоту отката и коэффициент отката и отправить их обратно. Например, если источник данных регулируется во время обхода контента, соединитель может задать для operationResult значение DatasourceError и отправить сведения о повторных попытках в соответствии с заголовком повтора в заголовках ответов из источника данных.

Сопоставление ошибок для OperationResult

Следующие ошибки перемещают подключение в состояние сбоя:

  • OperationResult.AuthenticationIssue

  • OperationResult.ValidationFailure

Другие коды операций будут рассматриваться как временные сбои и будут повторно использоваться при последующих обходах.

Связанные материалы