/// <summary>
/// Trains a model from a collection of custom forms in a blob storage container.
/// </summary>
/// <param name="trainingFilesUri">An externally accessible Azure storage blob container Uri.
/// For more information see <a href="https://docs.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set#upload-your-training-data"/>.</param>
/// <param name="useTrainingLabels">If <c>true</c>, use a label file created in the <link-to-label-tool-doc> to provide training-time labels for training a model. If <c>false</c>, the model will be trained from forms only.</param>
/// <param name="trainingOptions">A set of options available for configuring the training request.</param>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
/// <returns>
/// <para>A <see cref="TrainingOperation"/> to wait on this long-running operation. Its Value upon successful
/// completion will contain meta-data about the trained model.</para>
/// <para>Even if training fails, a model is created in the Form Recognizer account with an "invalid" status.
/// A <see cref="RequestFailedException"/> will be raised containing the modelId to access this invalid model.</para>
/// </returns>
public virtual async Task <TrainingOperation> StartTrainingAsync(Uri trainingFilesUri, bool useTrainingLabels, TrainingOptions trainingOptions = default, CancellationToken cancellationToken = default)
{
Argument.AssertNotNull(trainingFilesUri, nameof(trainingFilesUri));
trainingOptions ??= new TrainingOptions();
using DiagnosticScope scope = Diagnostics.CreateScope($"{nameof(FormTrainingClient)}.{nameof(StartTraining)}");
scope.Start();
try
{
var trainRequest = new TrainRequest(trainingFilesUri.AbsoluteUri)
{
SourceFilter = trainingOptions.TrainingFileFilter,
UseLabelFile = useTrainingLabels,
ModelName = trainingOptions.ModelName
};
ResponseWithHeaders <FormRecognizerTrainCustomModelAsyncHeaders> response = await ServiceClient.TrainCustomModelAsyncAsync(trainRequest).ConfigureAwait(false);
return(new TrainingOperation(response.Headers.Location, ServiceClient, Diagnostics));
}
catch (Exception e)
{
scope.Failed(e);
throw;
}
}
