Desarrollo con las API de Media Services v3Develop with Media Services v3 APIs

Logotipo de Media Services v3media services logo v3


Como desarrollador, puede usar la API de REST de Media Services o bibliotecas de cliente que le permitan interactuar con la API de REST para crear, administrar y mantener fácilmente flujos de trabajo multimedia personalizados.As a developer, you can use Media Services REST API or client libraries that allow you to interact with the REST API to easily create, manage, and maintain custom media workflows. La API de Media Services v3 se basa en la especificación OpenAPI (anteriormente conocida como Swagger).The Media Services v3 API is based on the OpenAPI specification (formerly known as a Swagger).

En este artículo se analizan las reglas que se aplican a las entidades y las API cuando se desarrolla con Media Services v3.This article discusses rules that apply to entities and APIs when you develop with Media Services v3.

Acceso a la API de Azure Media ServicesAccessing the Azure Media Services API

Para ser autorizado a acceder a recursos de Media Services y a Media Services API, se debe autenticar primero.To be authorized to access Media Services resources and the Media Services API, you must first be authenticated. Media Services admite la autenticación basada en Azure Active Directory (Azure AD).Media Services supports Azure Active Directory (Azure AD)-based authentication. Dos opciones comunes de autenticación son:Two common authentication options are:

  • Autenticación de la entidad de servicio: se usa para autenticar un servicio (por ejemplo: aplicaciones web, aplicaciones de funciones, aplicaciones lógicas, API y microservicios).Service principal authentication: Used to authenticate a service (for example: web apps, function apps, logic apps, API, and microservices). Las aplicaciones que normalmente utilizan este método de autenticación son las que ejecutan servicios de demonio, servicios de nivel intermedio o trabajos programados.Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs. Por ejemplo, para las aplicaciones web, siempre debe haber un nivel intermedio que se conecte a Media Services con una entidad de servicio.For example, for web apps there should always be a mid-tier that connects to Media Services with a Service Principal.
  • Autenticación de usuarios: se usa para autenticar a una persona que usa la aplicación para interactuar con recursos de Media Services.User authentication: Used to authenticate a person who is using the app to interact with Media Services resources. La aplicación interactiva debe pedir primero al usuario sus credenciales.The interactive app should first prompt the user for the user's credentials. Un ejemplo es una aplicación de consola de administración que usan los usuarios autorizados para supervisar trabajos de codificación o streaming en vivo.An example is a management console app used by authorized users to monitor encoding jobs or live streaming.

La API de Media Services requiere que el usuario o la aplicación que realiza las solicitudes de API REST tengan acceso al recurso de la cuenta de Media Services y usen un rol de Colaborador o Propietario.The Media Services API requires that the user or app making the REST API requests have access to the Media Services account resource and use a Contributor or Owner role. Se puede acceder a la API con la función Lector pero solo estarán disponibles las operaciones Obtener o Enumerar.The API can be accessed with the Reader role but only Get or List operations will be available.Para obtener más información, vea Control de acceso basado en rol de Azure (RBAC de Azure) para cuentas de Media Services. For more information, see Azure role-based access control (Azure RBAC) for Media Services accounts.

En lugar de crear una entidad de servicio, use las identidades administradas de los recursos de Azure para acceder a la API de Media Services a través de Azure Resource Manager.Instead of creating a service principal, consider using managed identities for Azure resources to access the Media Services API through Azure Resource Manager. Para obtener más información sobre las identidades administradas para los recursos de Azure, consulte ¿Qué es Managed Identities for Azure Resources?.To learn more about managed identities for Azure resources, see What is managed identities for Azure resources.

Entidad de servicio de Azure ADAzure AD service principal

La aplicación de Azure AD y la entidad de servicio deben estar en el mismo inquilino.The Azure AD app and service principal should be in the same tenant. Después de crear la aplicación, asigne al rol Colaborador o Propietario de la aplicación acceso a la cuenta de Media Services.After you create the app, give the app Contributor or Owner role access to the Media Services account.

Si no está seguro de tener permisos para crear una aplicación de Azure AD, consulte Permisos necesarios.If you're not sure whether you have permissions to create an Azure AD app, see Required permissions.

En la ilustración siguiente, los números representan el flujo de las solicitudes en orden cronológico:In the following figure, the numbers represent the flow of the requests in chronological order:

Autenticación de aplicaciones de nivel intermedio con AAD desde una API web

  1. Una aplicación de nivel medio solicita un token de acceso de Azure AD que tiene los siguientes parámetros:A middle-tier app requests an Azure AD access token that has the following parameters:

    • Punto de conexión de inquilino de Azure AD.Azure AD tenant endpoint.
    • URI del recurso de Media Services.Media Services resource URI.
    • URI del recurso de Media Services de REST.Resource URI for REST Media Services.
    • Valores de aplicación de Azure AD: el identificador de cliente y el secreto de cliente.Azure AD app values: the client ID and client secret.

    Para obtener todos los valores necesarios, consulte Acceso a la API de Azure Media Services.To get all the needed values, see Access Azure Media Services API.

  2. El token de acceso de Azure AD se envía al nivel intermedio.The Azure AD access token is sent to the middle tier.

  3. El nivel intermedio envía una solicitud a la API de REST de Azure Media Services con el token de Azure AD.The middle tier sends request to the Azure Media REST API with the Azure AD token.

  4. El nivel intermedio recibe los datos de Media Services.The middle tier gets back the data from Media Services.

EjemplosSamples

Consulte los siguientes ejemplos que muestran cómo conectarse con la entidad de servicio de Azure AD:See the following samples that show how to connect with Azure AD service principal:

Convenciones de nomenclaturaNaming conventions

Los nombres de recursos de Azure Media Services v3 (por ejemplo, recursos, trabajos y transformaciones) están sujetos a las restricciones de nomenclatura de Azure Resource Manager.Azure Media Services v3 resource names (for example, Assets, Jobs, Transforms) are subject to Azure Resource Manager naming constraints. De acuerdo con Azure Resource Manager, los nombres de los recursos siempre son únicos.In accordance with Azure Resource Manager, the resource names are always unique. Por lo tanto, puede usar cualquier cadena de identificador único (por ejemplo, GUID) para los nombres de recursos.Thus, you can use any unique identifier strings (for example, GUIDs) for your resource names.

Los nombres de recursos de Media Services no pueden incluir: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', el carácter de comilla simple o cualquier carácter de control.Media Services resource names can't include: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', the single quote character, or any control characters. Todos los demás caracteres se permiten.All other characters are allowed. La longitud máxima de un nombre de recurso es de 260 caracteres.The max length of a resource name is 260 characters.

Para más información sobre la nomenclatura de Azure Resource Manager, consulte: Convenciones de nomenclatura y Convenciones de nomenclatura.For more information about Azure Resource Manager naming, see Naming requirements and Naming conventions.

Nombres de archivos o blobs dentro de un recursoNames of files/blobs within an asset

Los nombres de los archivos o blobs dentro de un recurso deben seguir los requisitos para los nombres de blobs y los requisitos para los nombres NTFS.The names of files/blobs within an asset must follow both the blob name requirements and the NTFS name requirements. La razón de estos requisitos es que los archivos se puedan copiar desde Blob Storage a un disco NTFS local para su procesamiento.The reason for these requirements is the files can get copied from blob storage to a local NTFS disk for processing.

Operaciones de larga duraciónLong-running operations

Las operaciones marcadas con x-ms-long-running-operation en los archivos de Swagger de Azure Media Services son operaciones de larga duración.The operations marked with x-ms-long-running-operation in the Azure Media Services swagger files are long running operations.

Para obtener detalles sobre cómo realizar un seguimiento de las operaciones asincrónicas de Azure, consulte Operaciones asincrónicas.For details about how to track asynchronous Azure operations, see Async operations.

Media Services tiene las siguientes operaciones de larga duración:Media Services has the following long-running operations:

Si se envía correctamente una operación larga, recibirá un mensaje "201 Creado" y tendrá que sondear la finalización de la operación con el identificador de operación devuelto.On successful submission of a long operation, you receive a '201 Created' and must poll for operation completion using the returned operation ID.

En el artículo Seguimiento de las operaciones asincrónicas de Azure se explica de forma detallada cómo realizar un seguimiento del estado de las operaciones asincrónicas de Azure mediante los valores devueltos en la respuesta.The track asynchronous Azure operations article explains in depth how to track the status of asynchronous Azure operations through values returned in the response.

Solo se admite una operación de larga duración para un LiveEvent determinado o para cualquiera de sus LiveOutput asociados.Only one long-running operation is supported for a given Live Event or any of its associated Live Outputs. Una vez iniciada, la operación de larga duración se debe completar antes de iniciar una operación de larga duración posterior en el mismo LiveEvent o en cualquier LiveOutput asociado.Once started, a long running operation must complete before starting a subsequent long-running operation on the same LiveEvent or any associated Live Outputs. En el caso de los LiveEvent con varios LiveOutput, debe esperar a que se complete una operación de larga duración en un LiveOutput antes de desencadenar una operación de larga duración en otro LiveOutput.For Live Events with multiple Live Outputs, you must await the completion of a long running operation on one Live Output before triggering a long running operation on another Live Output.

SDKSDKs

Nota

No se garantiza que los SDK de Azure Media Services v3 sean seguros para subprocesos.The Azure Media Services v3 SDKs aren't guaranteed to be thread-safe. Al desarrollar una aplicación multiproceso, debe agregar su propia lógica de sincronización de subprocesos para proteger el cliente o usar un nuevo objeto AzureMediaServicesClient por subproceso.When developing a multi-threaded app, you should add your own thread synchronization logic to protect the client or use a new AzureMediaServicesClient object per thread. También debe tener cuidado con los problemas de subprocesos múltiples introducidos por objetos opcionales que proporciona el código al cliente (por ejemplo, una instancia de HttpClient en .NET).You should also be careful of multi-threading issues introduced by optional objects provided by your code to the client (like an HttpClient instance in .NET).

SDKSDK ReferenciaReference
SDK de .NET.NET SDK Referencia de .NET.NET ref
SDK de JavaJava SDK Referencia de JavaJava ref
SDK de PythonPython SDK Referencia de PythonPython ref
SDK de Node.jsNode.js SDK Referencia de Node.jsNode.js ref
Go SDKGo SDK Referencia de GoGo ref
SDK de RubyRuby SDK

Consulte tambiénSee also

Explorador de Azure Media ServicesAzure Media Services Explorer

Azure Media Services Explorer (AMSE) es una herramienta disponible para los clientes de Windows que desean obtener información acerca de Media Services.Azure Media Services Explorer (AMSE) is a tool available to Windows customers who want to learn about Media Services. AMSE es una aplicación de Winforms o C# que permite cargar, descargar, codificar, transmitir vídeo bajo demanda y contenido en directo con Media Services.AMSE is a Winforms/C# application that does upload, download, encode, stream VOD and live content with Media Services. Esta herramienta es para aquellos clientes que deseen probar Media Services sin escribir ningún código.The AMSE tool is for clients who want to test Media Services without writing any code. El código AMSE se proporciona como un recurso para los clientes que desean desarrollar con Media Services.The AMSE code is provided as a resource for customers who want to develop with Media Services.

AMSE es un proyecto de código abierto en el que el soporte técnico lo facilita la comunidad (se pueden notificar los problemas a https://github.com/Azure/Azure-Media-Services-Explorer/issues) ).AMSE is an Open Source project, support is provided by the community (issues can be reported to https://github.com/Azure/Azure-Media-Services-Explorer/issues). El proyecto ha adoptado el Código de conducta de código abierto de Microsoft.This project has adopted the Microsoft Open Source Code of Conduct. Para más información, consulte las preguntas frecuentes del código de conducta o escriba un correo electrónico a opencode@microsoft.com si tiene cualquier otra pregunta o comentario.For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any other questions or comments.

Filtrado, ordenación y paginación de entidades de Media ServicesFiltering, ordering, paging of Media Services entities

Consulte Filtrado, ordenación y paginación de entidades de Azure Media Services.See Filtering, ordering, paging of Azure Media Services entities.

Formule preguntas, realice comentarios y obtenga actualizacionesAsk questions, give feedback, get updates

Consulte el artículo Comunidad de Azure Media Services para ver diferentes formas de formular preguntas, enviar comentarios y obtener actualizaciones de Media Services.Check out the Azure Media Services community article to see different ways you can ask questions, give feedback, and get updates about Media Services.

Consulte tambiénSee also

Para obtener todos los valores necesarios, consulte Acceso a la API de Azure Media Services.To get all the needed values, see Access Azure Media Services API.

Pasos siguientesNext steps