SingleDocumentTranslationClient.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

// <auto-generated/>

#nullable disable

using System;
using System.Threading;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Core.Pipeline;

namespace Azure.AI.Translation.Document
{
    // Data plane generated client.
    /// <summary> The SingleDocumentTranslation service client. </summary>
    public partial class SingleDocumentTranslationClient
    {
        private const string AuthorizationHeader = "Ocp-Apim-Subscription-Key";
        private readonly AzureKeyCredential _keyCredential;
        private static readonly string[] AuthorizationScopes = new string[] { "https://cognitiveservices.azure.com/.default" };
        private readonly TokenCredential _tokenCredential;
        private readonly HttpPipeline _pipeline;
        private readonly Uri _endpoint;
        private readonly string _apiVersion;

        /// <summary> The ClientDiagnostics is used to provide tracing support for the client library. </summary>
        internal ClientDiagnostics ClientDiagnostics { get; }

        /// <summary> The HTTP pipeline for sending and receiving REST requests and responses. </summary>
        public virtual HttpPipeline Pipeline => _pipeline;

        /// <summary> Initializes a new instance of SingleDocumentTranslationClient for mocking. </summary>
        protected SingleDocumentTranslationClient()
        {
        }

        /// <summary> Initializes a new instance of SingleDocumentTranslationClient. </summary>
        /// <param name="endpoint"> Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. </param>
        /// <param name="credential"> A credential used to authenticate to an Azure Service. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="endpoint"/> or <paramref name="credential"/> is null. </exception>
        public SingleDocumentTranslationClient(Uri endpoint, AzureKeyCredential credential) : this(endpoint, credential, new DocumentTranslationClientOptions())
        {
        }

        /// <summary> Initializes a new instance of SingleDocumentTranslationClient. </summary>
        /// <param name="endpoint"> Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. </param>
        /// <param name="credential"> A credential used to authenticate to an Azure Service. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="endpoint"/> or <paramref name="credential"/> is null. </exception>
        public SingleDocumentTranslationClient(Uri endpoint, TokenCredential credential) : this(endpoint, credential, new DocumentTranslationClientOptions())
        {
        }

        /// <summary> Initializes a new instance of SingleDocumentTranslationClient. </summary>
        /// <param name="endpoint"> Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. </param>
        /// <param name="credential"> A credential used to authenticate to an Azure Service. </param>
        /// <param name="options"> The options for configuring the client. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="endpoint"/> or <paramref name="credential"/> is null. </exception>
        public SingleDocumentTranslationClient(Uri endpoint, AzureKeyCredential credential, DocumentTranslationClientOptions options)
        {
            Argument.AssertNotNull(endpoint, nameof(endpoint));
            Argument.AssertNotNull(credential, nameof(credential));
            options ??= new DocumentTranslationClientOptions();

            ClientDiagnostics = new ClientDiagnostics(options, true);
            _keyCredential = credential;
            _pipeline = HttpPipelineBuilder.Build(options, Array.Empty<HttpPipelinePolicy>(), new HttpPipelinePolicy[] { new AzureKeyCredentialPolicy(_keyCredential, AuthorizationHeader) }, new ResponseClassifier());
            _endpoint = endpoint;
            _apiVersion = options.Version;
        }

        /// <summary> Initializes a new instance of SingleDocumentTranslationClient. </summary>
        /// <param name="endpoint"> Supported document Translation endpoint, protocol and hostname, for example: https://{TranslatorResourceName}.cognitiveservices.azure.com/translator. </param>
        /// <param name="credential"> A credential used to authenticate to an Azure Service. </param>
        /// <param name="options"> The options for configuring the client. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="endpoint"/> or <paramref name="credential"/> is null. </exception>
        public SingleDocumentTranslationClient(Uri endpoint, TokenCredential credential, DocumentTranslationClientOptions options)
        {
            Argument.AssertNotNull(endpoint, nameof(endpoint));
            Argument.AssertNotNull(credential, nameof(credential));
            options ??= new DocumentTranslationClientOptions();

            ClientDiagnostics = new ClientDiagnostics(options, true);
            _tokenCredential = credential;
            _pipeline = HttpPipelineBuilder.Build(options, Array.Empty<HttpPipelinePolicy>(), new HttpPipelinePolicy[] { new BearerTokenAuthenticationPolicy(_tokenCredential, AuthorizationScopes) }, new ResponseClassifier());
            _endpoint = endpoint;
            _apiVersion = options.Version;
        }

        /// <summary> Submit a single document translation request to the Document Translation service. </summary>
        /// <param name="targetLanguage">
        /// Specifies the language of the output document.
        /// The target language must be one of the supported languages included in the translation scope.
        /// For example if you want to translate the document in German language, then use targetLanguage=de
        /// </param>
        /// <param name="documentTranslateContent"> Document Translate Request Content. </param>
        /// <param name="sourceLanguage">
        /// Specifies source language of the input document.
        /// If this parameter isn't specified, automatic language detection is applied to determine the source language.
        /// For example if the source document is written in English, then use sourceLanguage=en
        /// </param>
        /// <param name="category">
        /// A string specifying the category (domain) of the translation. This parameter is used to get translations
        /// from a customized system built with Custom Translator. Add the Category ID from your Custom Translator
        /// project details to this parameter to use your deployed customized system. Default value is: general.
        /// </param>
        /// <param name="allowFallback">
        /// Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist.
        /// Possible values are: true (default) or false.
        /// </param>
        /// <param name="cancellationToken"> The cancellation token to use. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="targetLanguage"/> or <paramref name="documentTranslateContent"/> is null. </exception>
        /// <remarks> Use this API to submit a single translation request to the Document Translation Service. </remarks>
        public virtual async Task<Response<BinaryData>> DocumentTranslateAsync(string targetLanguage, DocumentTranslateContent documentTranslateContent, string sourceLanguage = null, string category = null, bool? allowFallback = null, CancellationToken cancellationToken = default)
        {
            Argument.AssertNotNull(targetLanguage, nameof(targetLanguage));
            Argument.AssertNotNull(documentTranslateContent, nameof(documentTranslateContent));

            using MultipartFormDataRequestContent content = documentTranslateContent.ToMultipartRequestContent();
            RequestContext context = FromCancellationToken(cancellationToken);
            Response response = await DocumentTranslateAsync(targetLanguage, content, content.ContentType, sourceLanguage, category, allowFallback, context).ConfigureAwait(false);
            return Response.FromValue(response.Content, response);
        }

        /// <summary> Submit a single document translation request to the Document Translation service. </summary>
        /// <param name="targetLanguage">
        /// Specifies the language of the output document.
        /// The target language must be one of the supported languages included in the translation scope.
        /// For example if you want to translate the document in German language, then use targetLanguage=de
        /// </param>
        /// <param name="documentTranslateContent"> Document Translate Request Content. </param>
        /// <param name="sourceLanguage">
        /// Specifies source language of the input document.
        /// If this parameter isn't specified, automatic language detection is applied to determine the source language.
        /// For example if the source document is written in English, then use sourceLanguage=en
        /// </param>
        /// <param name="category">
        /// A string specifying the category (domain) of the translation. This parameter is used to get translations
        /// from a customized system built with Custom Translator. Add the Category ID from your Custom Translator
        /// project details to this parameter to use your deployed customized system. Default value is: general.
        /// </param>
        /// <param name="allowFallback">
        /// Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist.
        /// Possible values are: true (default) or false.
        /// </param>
        /// <param name="cancellationToken"> The cancellation token to use. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="targetLanguage"/> or <paramref name="documentTranslateContent"/> is null. </exception>
        /// <remarks> Use this API to submit a single translation request to the Document Translation Service. </remarks>
        public virtual Response<BinaryData> DocumentTranslate(string targetLanguage, DocumentTranslateContent documentTranslateContent, string sourceLanguage = null, string category = null, bool? allowFallback = null, CancellationToken cancellationToken = default)
        {
            Argument.AssertNotNull(targetLanguage, nameof(targetLanguage));
            Argument.AssertNotNull(documentTranslateContent, nameof(documentTranslateContent));

            using MultipartFormDataRequestContent content = documentTranslateContent.ToMultipartRequestContent();
            RequestContext context = FromCancellationToken(cancellationToken);
            Response response = DocumentTranslate(targetLanguage, content, content.ContentType, sourceLanguage, category, allowFallback, context);
            return Response.FromValue(response.Content, response);
        }

        /// <summary>
        /// [Protocol Method] Submit a single document translation request to the Document Translation service
        /// <list type="bullet">
        /// <item>
        /// <description>
        /// This <see href="https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/ProtocolMethods.md">protocol method</see> allows explicit creation of the request and processing of the response for advanced scenarios.
        /// </description>
        /// </item>
        /// <item>
        /// <description>
        /// Please try the simpler <see cref="DocumentTranslateAsync(string,DocumentTranslateContent,string,string,bool?,CancellationToken)"/> convenience overload with strongly typed models first.
        /// </description>
        /// </item>
        /// </list>
        /// </summary>
        /// <param name="targetLanguage">
        /// Specifies the language of the output document.
        /// The target language must be one of the supported languages included in the translation scope.
        /// For example if you want to translate the document in German language, then use targetLanguage=de
        /// </param>
        /// <param name="content"> The content to send as the body of the request. </param>
        /// <param name="contentType"> Content Type as multipart/form-data. Allowed values: "multipart/form-data". </param>
        /// <param name="sourceLanguage">
        /// Specifies source language of the input document.
        /// If this parameter isn't specified, automatic language detection is applied to determine the source language.
        /// For example if the source document is written in English, then use sourceLanguage=en
        /// </param>
        /// <param name="category">
        /// A string specifying the category (domain) of the translation. This parameter is used to get translations
        /// from a customized system built with Custom Translator. Add the Category ID from your Custom Translator
        /// project details to this parameter to use your deployed customized system. Default value is: general.
        /// </param>
        /// <param name="allowFallback">
        /// Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist.
        /// Possible values are: true (default) or false.
        /// </param>
        /// <param name="context"> The request context, which can override default behaviors of the client pipeline on a per-call basis. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="targetLanguage"/> or <paramref name="content"/> is null. </exception>
        /// <exception cref="RequestFailedException"> Service returned a non-success status code. </exception>
        /// <returns> The response returned from the service. </returns>
        public virtual async Task<Response> DocumentTranslateAsync(string targetLanguage, RequestContent content, string contentType, string sourceLanguage = null, string category = null, bool? allowFallback = null, RequestContext context = null)
        {
            Argument.AssertNotNull(targetLanguage, nameof(targetLanguage));
            Argument.AssertNotNull(content, nameof(content));

            using var scope = ClientDiagnostics.CreateScope("SingleDocumentTranslationClient.DocumentTranslate");
            scope.Start();
            try
            {
                using HttpMessage message = CreateDocumentTranslateRequest(targetLanguage, content, contentType, sourceLanguage, category, allowFallback, context);
                return await _pipeline.ProcessMessageAsync(message, context).ConfigureAwait(false);
            }
            catch (Exception e)
            {
                scope.Failed(e);
                throw;
            }
        }

        /// <summary>
        /// [Protocol Method] Submit a single document translation request to the Document Translation service
        /// <list type="bullet">
        /// <item>
        /// <description>
        /// This <see href="https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/ProtocolMethods.md">protocol method</see> allows explicit creation of the request and processing of the response for advanced scenarios.
        /// </description>
        /// </item>
        /// <item>
        /// <description>
        /// Please try the simpler <see cref="DocumentTranslate(string,DocumentTranslateContent,string,string,bool?,CancellationToken)"/> convenience overload with strongly typed models first.
        /// </description>
        /// </item>
        /// </list>
        /// </summary>
        /// <param name="targetLanguage">
        /// Specifies the language of the output document.
        /// The target language must be one of the supported languages included in the translation scope.
        /// For example if you want to translate the document in German language, then use targetLanguage=de
        /// </param>
        /// <param name="content"> The content to send as the body of the request. </param>
        /// <param name="contentType"> Content Type as multipart/form-data. Allowed values: "multipart/form-data". </param>
        /// <param name="sourceLanguage">
        /// Specifies source language of the input document.
        /// If this parameter isn't specified, automatic language detection is applied to determine the source language.
        /// For example if the source document is written in English, then use sourceLanguage=en
        /// </param>
        /// <param name="category">
        /// A string specifying the category (domain) of the translation. This parameter is used to get translations
        /// from a customized system built with Custom Translator. Add the Category ID from your Custom Translator
        /// project details to this parameter to use your deployed customized system. Default value is: general.
        /// </param>
        /// <param name="allowFallback">
        /// Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist.
        /// Possible values are: true (default) or false.
        /// </param>
        /// <param name="context"> The request context, which can override default behaviors of the client pipeline on a per-call basis. </param>
        /// <exception cref="ArgumentNullException"> <paramref name="targetLanguage"/> or <paramref name="content"/> is null. </exception>
        /// <exception cref="RequestFailedException"> Service returned a non-success status code. </exception>
        /// <returns> The response returned from the service. </returns>
        public virtual Response DocumentTranslate(string targetLanguage, RequestContent content, string contentType, string sourceLanguage = null, string category = null, bool? allowFallback = null, RequestContext context = null)
        {
            Argument.AssertNotNull(targetLanguage, nameof(targetLanguage));
            Argument.AssertNotNull(content, nameof(content));

            using var scope = ClientDiagnostics.CreateScope("SingleDocumentTranslationClient.DocumentTranslate");
            scope.Start();
            try
            {
                using HttpMessage message = CreateDocumentTranslateRequest(targetLanguage, content, contentType, sourceLanguage, category, allowFallback, context);
                return _pipeline.ProcessMessage(message, context);
            }
            catch (Exception e)
            {
                scope.Failed(e);
                throw;
            }
        }

        internal HttpMessage CreateDocumentTranslateRequest(string targetLanguage, RequestContent content, string contentType, string sourceLanguage, string category, bool? allowFallback, RequestContext context)
        {
            var message = _pipeline.CreateMessage(context, ResponseClassifier200);
            var request = message.Request;
            request.Method = RequestMethod.Post;
            var uri = new RawRequestUriBuilder();
            uri.Reset(_endpoint);
            uri.AppendRaw("/translator", false);
            uri.AppendPath("/document:translate", false);
            uri.AppendQuery("targetLanguage", targetLanguage, true);
            uri.AppendQuery("api-version", _apiVersion, true);
            if (sourceLanguage != null)
            {
                uri.AppendQuery("sourceLanguage", sourceLanguage, true);
            }
            if (category != null)
            {
                uri.AppendQuery("category", category, true);
            }
            if (allowFallback != null)
            {
                uri.AppendQuery("allowFallback", allowFallback.Value, true);
            }
            request.Uri = uri;
            request.Headers.Add("Accept", "application/octet-stream");
            request.Headers.Add("content-type", contentType);
            request.Content = content;
            return message;
        }

        private static RequestContext DefaultRequestContext = new RequestContext();
        internal static RequestContext FromCancellationToken(CancellationToken cancellationToken = default)
        {
            if (!cancellationToken.CanBeCanceled)
            {
                return DefaultRequestContext;
            }

            return new RequestContext() { CancellationToken = cancellationToken };
        }

        private static ResponseClassifier _responseClassifier200;
        private static ResponseClassifier ResponseClassifier200 => _responseClassifier200 ??= new StatusCodeClassifier(stackalloc ushort[] { 200 });
    }
}