Compartir a través de

Manage package flight submissions (Administrar envíos de paquetes piloto)

  • Artículo

La API de envío de Microsoft Store proporciona métodos que puedes usar para administrar envíos de paquetes piloto para tus aplicaciones, incluidas las implementaciones graduales de paquetes. Para obtener una introducción a la API de envío de Microsoft Store, incluidos los requisitos previos para usar la API, consulte Crear y administrar envíos mediante los servicios de Microsoft Store.

Importante

Si usas la API de envío de Microsoft Store para crear un envío para un paquete piloto, asegúrate de realizar más cambios en el envío solo mediante la API, en lugar del Centro de partners. Si usa el panel para cambiar un envío que creó originalmente mediante la API, ya no podrá cambiar ni confirmar ese envío mediante la API. En algunos casos, el envío podría quedar en un estado de error que le impedirá continuar con el proceso de envío. Si esto ocurre, debe eliminar el envío y crear uno nuevo.

Métodos para administrar envíos de paquetes piloto

Use los métodos siguientes para obtener, crear, actualizar, confirmar o eliminar un envío de paquete piloto. Para poder usar estos métodos, el paquete piloto ya debe existir en el Centro de partners. Puedes crear un paquete piloto en el Centro de partners o usando los métodos de la API de envío de Microsoft Store descritos en Administrar paquetes piloto.

Método URI Descripción
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Obtener un envío de paquete piloto existente
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status Obtener el estado de un envío de paquete piloto existente
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions Crear un nuevo envío de paquete piloto
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Actualización de un envío de paquete piloto existente
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit Confirmación de un envío de paquete piloto nuevo o actualizado
Delete https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Eliminar un envío de paquete piloto

Crear un envío de paquete piloto

Para crear un envío para un paquete piloto, siga este proceso.

  1. Si aún no lo ha hecho, complete los requisitos previos que se describen en Crear y administrar envíos mediante los servicios de Microsoft Store, incluida la asociación de una aplicación de Azure AD con su cuenta del Centro de partners y la obtención de su Id. y clave de cliente. Sólo es necesario hacer esto una vez; después de tener el Id. y la clave del cliente, puede reutilizarlos en cualquier momento que los necesite para crear un nuevo token de acceso de Azure AD.

  2. Obtener un token de acceso de Azure AD. Debe pasar este token de acceso a los métodos de la API de envío de Microsoft Store. Una vez que haya obtenido un token de acceso, tiene 60 minutos para usarlo antes de que expire. Una vez que expire el token, puede obtener uno nuevo.

  3. Cree un envío de paquete piloto ejecutando el siguiente método en la API de envío de Microsoft Store. Este método crea un nuevo envío en curso, que es una copia del último envío publicado.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions

    El cuerpo de la respuesta contiene un recurso de envío piloto que incluye el identificador del nuevo envío, el URI de firma de acceso compartido (SAS) para cargar los paquetes para el envío a Azure Blob Storage y los datos del nuevo envío (incluidos todos los listados e información de precios).

    Nota:

    Un URI de SAS proporciona acceso a un recurso seguro en el almacenamiento de Azure sin necesidad de claves de cuenta. Para obtener información de antecedentes sobre los URI de SAS y su uso con Azure Blob Storage, consulte Firma de acceso compartido, parte 1: comprender el modelo SAS y Firma de acceso compartido, parte 2: crear y usar un SAS con almacenamiento de blobs.

  4. Si va a agregar nuevos paquetes para el envío, prepare los paquetes y agréguelos a un archivo ZIP.

  5. Revise los datos de envío de vuelos con los cambios necesarios para el nuevo envío y ejecute el siguiente método para actualizar el envío del paquete piloto.

    PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}

    Nota:

    Si va a agregar nuevos paquetes para el envío, asegúrese de actualizar los datos de envío para hacer referencia al nombre y la ruta de acceso relativa de estos archivos en el archivo ZIP.

  6. Si va a agregar nuevos paquetes para el envío, cargue el archivo ZIP en Azure Blob Storage mediante el URI de SAS que se proporcionó en el cuerpo de la respuesta del método POST al que llamó anteriormente. Existen diferentes bibliotecas de Azure que puede usar para hacer esto en una variedad de plataformas, que incluyen:

    El siguiente ejemplo de código C# muestra cómo cargar un archivo ZIP en Azure Blob Storage mediante la clase CloudBlockBlob en la biblioteca cliente de Azure Storage para .NET. Este ejemplo supone que el archivo ZIP ya se ha escrito en un objeto de secuencia.

    string sasUrl = "https://productingestionbin1.blob.core.windows.net/ingestion/26920f66-b592-4439-9a9d-fb0f014902ec?sv=2014-02-14&sr=b&sig=usAN0kNFNnYE2tGQBI%2BARQWejX1Guiz7hdFtRhyK%2Bog%3D&se=2016-06-17T20:45:51Z&sp=rwl";
Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob blockBob =
    new Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob(new System.Uri(sasUrl));
await blockBob.UploadFromStreamAsync(stream);

  7. Confirme el envío del paquete piloto ejecutando el método siguiente. Esto alertará al Centro de partners de que ha terminado con el envío y que las actualizaciones ahora deberían aplicarse a su cuenta.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit

  8. Compruebe el estado de confirmación ejecutando el método siguiente para obtener el estado del envío del paquete piloto.

    GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status

    Para confirmar el estado del envío, revise el valor estado en el cuerpo de respuesta. Este valor debe cambiar de CommitStarted a PreProcessing si la solicitud se realiza correctamente, o bien a CommitFailed si hay errores en la solictud. Si hay errores, el campo statusDetails contiene más detalles sobre el error.

  9. Una vez que la confirmación se ha completado con éxito, el envío se destina al almacén para su ingesta. Puede continuar supervisando el progreso del envío utilizando el método anterior o visitando el Centro de partners.

Ejemplos de código

En los artículos siguientes se proporcionan ejemplos de código detallados que muestran cómo crear un envío de paquete piloto en varios lenguajes de programación diferentes:

Módulo StoreBroker de PowerShell

Como alternativa a llamar directamente a la API de envío de Microsoft Store, también proporcionamos un módulo de PowerShell de código abierto que implementa una interfaz de la línea de comandos sobre la API. Este módulo se denomina StoreBroker. Puede utilizar este módulo para administrar los envíos de aplicaciones, versiones piloto y complementos desde la línea de comandos en lugar de llamar directamente a la API de envío de Microsoft Store, o simplemente puede examinar el origen para ver más ejemplos de cómo llamar a esta API. El módulo StoreBroker se usa activamente en Microsoft como la principal forma en que muchas aplicaciones propias se envían al almaceń.

Para obtener más información, consulte nuestra página StoreBroker en GitHub.

Administrar un lanzamiento gradual de paquetes para un envío de paquete piloto

Puedes implementar gradualmente los paquetes actualizados en un envío de paquete piloto a un porcentaje de los clientes de la aplicación en Windows 10 y Windows 11. Esto le permite supervisar los comentarios y los datos analíticos de los paquetes específicos para asegurarse de que está seguro de la actualización antes de implementarla de forma más amplia. Puede cambiar el porcentaje de lanzamiento (o detener la actualización) de un envío publicado sin tener que crear un nuevo envío. Para obtener más información, incluidas las instrucciones para habilitar y administrar un lanzamiento gradual de paquetes en el Centro de partners, consulte este artículo.

Para habilitar mediante programación un lanzamiento gradual de paquetes para un envío de paquete piloto, siga este proceso mediante métodos en la API de envío de Microsoft Store:

  1. Cree un envío de paquete piloto o obtenga un envío de paquete piloto.
  2. En los datos de respuesta, busque el recurso packageRollout , establezca el campo isPackageRollout en true y establezca el campo packageRolloutPercentage en el porcentaje de los clientes de la aplicación que deben obtener los paquetes actualizados.
  3. Pase los datos de envío de paquetes piloto actualizados al método de envío de paquete piloto.

Una vez habilitada una implementación gradual de paquetes para un envío de paquete piloto, puedes usar los métodos siguientes para obtener, actualizar, detener o finalizar el lanzamiento gradual mediante programación.

Método URI Descripción
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout Obtener la información de lanzamiento gradual de un envío de paquete piloto
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage Actualizar el porcentaje de lanzamiento gradual para un envío de paquete piloto
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout Detener el lanzamiento gradual para un envío de paquete piloto
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout Finalización del lanzamiento gradual para un envío de paquete piloto

Recursos de datos

Los métodos de la API de envío de Microsoft Store para administrar envíos de paquetes piloto usan los siguientes recursos de datos JSON.

Recurso de envío de vuelos

Este recurso describe un envío de paquete piloto.

{
  "id": "1152921504621243649",
  "flightId": "cd2e368a-0da5-4026-9f34-0e7934bc6f23",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [],
    "warnings": [],
    "certificationReports": []
  },
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
  "fileUploadUrl": "https://productingestionbin1.blob.core.windows.net/ingestion/8b389577-5d5e-4cbe-a744-1ff2e97a9eb8?sv=2014-02-14&sr=b&sig=wgMCQPjPDkuuxNLkeG35rfHaMToebCxBNMPw7WABdXU%3D&se=2016-06-17T21:29:44Z&sp=rwl",
  "targetPublishMode": "Immediate",
  "targetPublishDate": "",
  "notesForCertification": "No special steps are required for certification of this app."
}

Este recurso tiene los siguientes valores.

Valor Tipo Descripción
id string Identificador del envío.
flightId string Identificador del paquete piloto al que está asociado el envío.
status string El estado del envío. Este puede ser uno de los siguientes valores:
  • None
  • Canceled
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Publicación
  • Publicado
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Certificación
  • CertificationFailed
  • Versión
  • ReleaseFailed
statusDetails objeto Un recurso de detalles de estado que contiene detalles adicionales sobre el estado del envío, incluida información sobre cualquier error.
flightPackages array Contiene recursos del paquete piloto que proporcionan detalles sobre cada paquete del envío.
packageDeliveryOptions objeto Un recurso de opciones de entrega de paquetes que contiene la implementación gradual de paquetes y la configuración de actualización obligatoria para el envío.
fileUploadUrl string El URI de firma de acceso compartido (SAS) para cargar cualquier paquete para el envío. Si añade nuevos paquetes para el envío, cargue el archivo ZIP que contiene los paquetes para ese URI. Para obtener más información, consulta Crear un envío de paquete piloto.
targetPublishMode string El modo de publicación para el envío. Este puede ser uno de los siguientes valores:
  • Inmediato
  • Manual
  • SpecificDate
targetPublishDate string La fecha de publicación para el envío en formato ISO 8601, si targetPublishMode está establecido en SpecificDate.
notesForCertification string Proporciona información adicional para los evaluadores de certificación, como las credenciales de la cuenta de prueba y los pasos para acceder a las características y comprobar. Para obtener más información, consulte Notas para la certificación.

Recurso de detalles de estado

Este recurso contiene detalles adicionales sobre el estado de un envío. Este recurso tiene los siguientes valores.

Valor Tipo Descripción
errors objeto Una matriz de recurso de detalles de estado que contiene los detalles de error para el envío.
advertencias objeto Una matriz de recurso de detalles de estado que contiene los detalles de advertencia para el envío.
certificationReports objeto Una matriz de recursos de informe de certificación que proporciona acceso a los datos del informe de certificación para el envío. Puede examinar estos informes para obtener más información si la certificación falla.

Recurso de detalle de estado

Este recurso contiene información adicional sobre cualquier error relacionado o advertencias para un envío. Este recurso tiene los siguientes valores.

Valor Tipo Descripción
código string Un código de estado de envío que describe el tipo de error o advertencia.
detalles string Un mensaje con más detalle sobre el problema.

Recurso de informe de certificación

Este recurso proporciona acceso a los datos del informe de certificación para un envío. Este recurso tiene los siguientes valores.

Valor Tipo Descripción
date string La fecha y hora en que se generó el informe en formato ISO 8601.
reportUrl string La URL en la que puede acceder al informe.

Recurso de paquete piloto

Este recurso proporciona detalles sobre un paquete en un envío.

{
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
}

Este recurso tiene los siguientes valores.

Nota:

Al llamar al método de envío de paquete piloto de actualización, solo se requieren los valores fileName, fileStatus, minimumDirectXVersion y minimumSystemRam de este objeto en el cuerpo de la solicitud. Los demás valores se rellenan mediante el Centro de partners.

Valor Tipo Descripción
fileName string Nombre del paquete.
fileStatus string Estado del paquete. Este puede ser uno de los siguientes valores:
  • None
  • PendingUpload
  • Cargado
  • PendingDelete
id string Identificador que identifica de forma única el paquete. Este valor lo usa el Centro de partners.
version string Versión del paquete de la aplicación. Para obtener más información, consulte Numeración de versiones del paquete.
Arquitectura string Arquitectura del paquete de la aplicación (por ejemplo, ARM).
languages array Matriz de códigos de idioma para los idiomas que admite la aplicación. Para obtener más información, consulte Para obtener más información, vea Idiomas admitidos.
capabilities array Matriz de funcionalidades requeridas por el paquete. Para obtener más información sobre las funcionalidades, consulte Declaraciones de funcionalidad de la aplicación.
minimumDirectXVersion string Versión mínima de DirectX compatible con el paquete de la aplicación. Esto solo se puede establecer para aplicaciones destinadas a Windows 8.x; se omite para las aplicaciones que tienen como destino otras versiones. Este puede ser uno de los siguientes valores:
  • None
  • DirectX93
  • DirectX100
minimumSystemRam string Ram mínima que requiere el paquete de la aplicación. Esto solo se puede establecer para aplicaciones destinadas a Windows 8.x; se omite para las aplicaciones que tienen como destino otras versiones. Este puede ser uno de los siguientes valores:
  • None
  • Memory2GB

Recurso de opciones de entrega de paquetes

Este recurso contiene la implementación gradual de paquetes y la configuración de actualización obligatoria para el envío.

{
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
}

Este recurso tiene los siguientes valores.

Valor Tipo Descripción
packageRollout objeto Un recurso de lanzamiento de paquetes que contiene la configuración gradual del lanzamiento de paquetes para el envío.
isMandatoryUpdate boolean Indica si desea tratar los paquetes de este envío como obligatorios para las actualizaciones de aplicaciones autoinstalados. Para obtener más información sobre los paquetes obligatorios para las actualizaciones de aplicaciones autoinstalados, consulta Descargar e instalar actualizaciones de paquetes para la aplicación.
mandatoryUpdateEffectiveDate date Fecha y hora en que los paquetes de este envío son obligatorios, en formato ISO 8601 y zona horaria UTC.

Recurso de lanzamiento de paquetes

Este recurso contiene la configuración de lanzamiento gradual de paquetes para el envío. Este recurso tiene los siguientes valores.

Valor Tipo Descripción
isPackageRollout boolean Indica si la implementación gradual de paquetes está habilitada para el envío.
packageRolloutPercentage flotante Porcentaje de usuarios que recibirán los paquetes en el lanzamiento gradual.
packageRolloutStatus string Una de las siguientes cadenas que indica el estado del lanzamiento gradual de paquetes:
  • PackageRolloutNotStarted
  • PackageRolloutInProgress
  • PackageRolloutComplete
  • PackageRolloutStopped
fallbackSubmissionId string Identificador del envío que recibirán los clientes que no obtengan los paquetes de lanzamiento gradual.

Nota:

El desarrollador asigna los valores packageRolloutStatus y fallbackSubmissionId y no está pensado para que lo establezca el desarrollador. Si incluye estos valores en un cuerpo de la solicitud, se omitirán estos valores.

Enumeraciones

Estos métodos utilizan las siguientes enumeraciones.

Código de estado de envío

Los códigos siguientes representan el estado de un envío.

Código Descripción
None No se ha especificado ningún código.
InvalidArchive El archivo ZIP que contiene el paquete no es válido o tiene un formato de archivo desconocido.
MissingFiles El archivo ZIP no tiene todos los archivos que figuran en los datos de envío o están en la ubicación incorrecta del archivo.
PackageValidationFailed Uno o más paquetes de su envío no se pudieron validar.
InvalidParameterValue Uno de los parámetros del cuerpo de la solicitud no es válido.
InvalidOperation La operación que intentó no es válida.
InvalidState La operación que intentó no es válida para el estado actual de la versión piloto del paquete.
ResourceNotFound No se pudo encontrar la versión piloto del paquete especificado.
ServiceError Un error de servicio interno impidió que la solicitud se realizara correctamente. Inténtelo de nuevo.
ListingOptOutWarning El desarrollador eliminó un listado de un envío anterior o no incluyó información de listado compatible con el paquete.
ListingOptInWarning El desarrollador agregó un listado.
UpdateOnlyWarning El desarrollador está intentando insertar algo que sólo admite actualizaciones.
Otros El envío se encuentra en un estado no reconocido o sin clasificar.
PackageValidationWarning El proceso de validación del paquete generó una advertencia.