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, consulta 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 dejarse en un estado de error en el que no puede continuar en el proceso de envío. Si esto ocurre, debe eliminar el envío y crear un nuevo envío.

Métodos para administrar envíos de paquetes piloto

Usa los siguientes métodos 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 mediante 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
POST 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} Actualizar un envío de paquete piloto existente
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit Confirmar 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 de un paquete piloto, sigue este proceso.

  1. Si aún no lo ha hecho, complete los requisitos previos descritos en Creación y administración de envíos mediante 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 del identificador y la clave de cliente. Solo tienes que hacerlo una vez; cuando tengas el identificador y la clave de cliente, puedes volver a usarlos siempre que necesites crear un nuevo token de acceso de Azure AD.

  2. Obtenga un token de acceso de Azure AD. Debes 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. Si el token expira, puedes 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 de tu ú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 Azure Storage sin necesidad de claves de cuenta. Para obtener información general sobre los URI de SAS y su uso con Azure Blob Storage, consulte Firmas de acceso compartido, parte 1: Descripción del modelo saS y las firmas de acceso compartido, parte 2: Creación y uso de una SAS con Blob Storage.

  4. Si estás agregando nuevos paquetes para el envío, prepara los paquetes y agrégalos 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 de 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 respuesta del método POST al que llamó anteriormente. Hay varias bibliotecas de Azure, que puedes usar para hacer esto en una variedad de plataformas, como:

    En el siguiente ejemplo de código de C# se muestra cómo cargar un archivo ZIP en Azure Blob Storage mediante la clase CloudBlockBlob en la biblioteca cliente de Azure Storage para .NET. En este ejemplo se 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. Ejecuta el siguiente método para confirmar el envío de paquete piloto. Esto le avisará al Centro de partners que haya terminado con el envío y que las actualizaciones se aplicarán ahora a su cuenta.

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

  8. Comprueba el estado de confirmación ejecutando el siguiente método para obtener el estado del envío de 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, revisa el valor de status en el cuerpo de la respuesta. Este valor debe cambiar de CommitStarted a PreProcessing si la solicitud se realiza correctamente o a CommitFailed si hay errores en la solicitud. Si hay errores, el campo statusDetails contendrá más detalles sobre el error.

  9. Después de completarse correctamente la confirmación, el envío se remite a la Tienda para su ingesta. Puedes seguir supervisando el progreso del envío mediante el método anterior o visitando el Centro de partners.

Ejemplos de código

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

Módulo de PowerShell de StoreBroker

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 línea de comandos sobre la API. Este módulo se denomina StoreBroker. Puedes usar este módulo para administrar los envíos de aplicaciones, vuelos y complementos desde la línea de comandos en lugar de llamar directamente a la API de envío de Microsoft Store, o simplemente puedes 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 a la Tienda.

Para obtener más información, consulta nuestra página storeBroker en GitHub.

Administrar un lanzamiento de paquete gradual 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 te permite supervisar los comentarios y los datos analíticos de los paquetes específicos para asegurarte de que estás seguro sobre la actualización antes de hacer un lanzamiento más amplio. Puedes cambiar el porcentaje de lanzamiento (o detener la actualización) para 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 piloto de paquete, siga este proceso mediante métodos en la API de envío de Microsoft Store:

  1. Crea un envío de paquete piloto u obtén 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. Pasa los datos de envío de paquete piloto actualizados al método de actualización de un envío de paquete piloto.

Después de habilitar un lanzamiento de paquete gradual para un envío de paquete piloto, puedes usar los siguientes métodos para obtener, actualizar, detener o finalizar mediante programación el lanzamiento gradual.

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
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage Actualizar el porcentaje de lanzamiento gradual de un envío de paquete piloto
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout Detener el lanzamiento gradual de un envío de paquete piloto
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout Finalizar el lanzamiento gradual de 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.

Recursos de envío de paquete piloto

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.

Value Tipo Descripción
id string Identificador del envío.
flightId string Identificador del paquete piloto al que está asociado el envío.
status string Estado del envío. Puede ser uno de los siguientes valores:
  • Ninguno
  • Canceled
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Publicación
  • Publicado
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Certificación
  • CertificationFailed
  • Release
  • ReleaseFailed
statusDetails object Un recurso de detalles de estado que contiene detalles adicionales sobre el estado del envío, incluida la información sobre los errores.
flightPackages array Contiene recursos de paquete piloto que proporcionan detalles acerca de cada paquete del envío.
packageDeliveryOptions object Un recurso de opciones de entrega de paquete que contiene el lanzamiento de paquete gradual y la configuración de actualización obligatoria para el envío.
fileUploadUrl string URI de firma de acceso compartido (SAS) para cargar los paquetes para el envío. Si estás agregando nuevos paquetes para el envío, carga el archivo ZIP que contiene los paquetes en este URI. Para obtener más información, consulta Crear un envío de paquete piloto.
targetPublishMode string Modo de publicación del envío. Puede ser uno de los siguientes valores:
  • Inmediata
  • Manual
  • SpecificDate
targetPublishDate string Fecha de publicación del envío en formato ISO 8601, si el valor targetPublishMode se establece en SpecificDate.
notesForCertification string Proporciona información adicional de los evaluadores de certificación como, por ejemplo, las credenciales de la cuenta de prueba y los pasos para obtener acceso y comprobar las características. Para obtener más información, consulta 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.

Value Tipo Descripción
errors object Una matriz de recursos de detalles de estado que contienen los detalles de errores del envío.
warnings object Una matriz de recursos de detalles de estado que contienen los detalles de advertencias del envío.
certificationReports object Una matriz de recursos de informe de certificación que proporcionan acceso a los datos del informe de certificación del envío. Si se produce un error en la certificación, puedes examinar estos informes para obtener más información.

Recurso de detalle de estado

Este recurso contiene información adicional acerca de las advertencias o los errores relacionados de un envío. Este recurso tiene los siguientes valores.

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

Recurso de informe de certificación

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

Value Tipo Descripción
date string Fecha y hora en que se generó el informe, en formato ISO 8601.
reportUrl string Dirección URL en la que puedes obtener acceso 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.

Value Tipo Descripción
fileName string Nombre del paquete.
fileStatus string Estado del paquete. Puede ser uno de los siguientes valores:
  • Ninguno
  • PendingUpload
  • Cargado
  • PendingDelete
id string Id. que identifica de manera exclusiva el paquete. El Centro de partners usa este valor.
version string Versión del paquete de aplicación. Para obtener más información, consulta Numeración de la versión del paquete.
arquitectura string Arquitectura del paquete de 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, consulta Idiomas admitidos.
capabilities array Matriz de funcionalidades necesarias para el paquete. Para obtener más información acerca de las funcionalidades, consulta Declaraciones de funcionalidades de las aplicaciones.
minimumDirectXVersion string Versión mínima de DirectX que admite el paquete de aplicación. Solo se puede establecer para las aplicaciones diseñadas para Windows 8.x; se omite para las aplicaciones diseñadas para otras versiones. Puede ser uno de los siguientes valores:
  • Ninguno
  • DirectX93
  • DirectX100
minimumSystemRam string RAM mínima que requiere el paquete de aplicación. Solo se puede establecer para las aplicaciones diseñadas para Windows 8.x; se omite para las aplicaciones diseñadas para otras versiones. Puede ser uno de los siguientes valores:
  • Ninguno
  • Memory2GB

Recurso de opciones de entrega de paquete

Este recurso contiene ajustes de lanzamiento de paquete gradual y 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.

Value Tipo Descripción
packageRollout object Un recurso de lanzamiento de paquete que contiene la configuración del lanzamiento de paquete gradual para el envío.
isMandatoryUpdate boolean Indica si vas a tratar los paquetes de este envío como obligatorios para la instalación automática de actualizaciones de la aplicación. Para obtener más información sobre los paquetes obligatorios para la instalación automática de actualizaciones de la aplicación, consulta Descargar e instalar actualizaciones de paquete para tu aplicación.
mandatoryUpdateEffectiveDate date La fecha y la hora en que los paquetes de este envío se convierten en obligatorios, en formato ISO 8601 y zona horaria UTC.

Recurso de lanzamiento de paquete

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

Value Tipo Descripción
isPackageRollout boolean Indica si el lanzamiento de paquete gradual está habilitado para el envío.
packageRolloutPercentage FLOAT El porcentaje de usuarios que recibirá los paquetes en el lanzamiento gradual.
packageRolloutStatus string Una de las siguientes cadenas, que indica el estado del lanzamiento de paquete gradual:
  • PackageRolloutNotStarted
  • PackageRolloutInProgress
  • PackageRolloutComplete
  • PackageRolloutStopped
fallbackSubmissionId string El identificador del envío que recibirán los clientes que no obtengan los paquetes de lanzamiento gradual.

Nota

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

Enumeraciones

Estos métodos usan las enumeraciones siguientes.

Código de estado del envío

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

Código Descripción
Ninguno No se especificó ningún código.
InvalidArchive El archivo ZIP que contiene el paquete no es válido o tiene un formato de archivo no reconocido.
MissingFiles El archivo ZIP no tiene todos los archivos que se enumeran en los datos del envío o estos se encuentran en una ubicación incorrecta en el archivo.
PackageValidationFailed Uno o varios paquetes de tu 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 intentaste realizar no es válida.
InvalidState La operación que intentaste realizar no es válida para el estado actual del paquete piloto.
ResourceNotFound No se pudo encontrar el paquete piloto especificado.
ServiceError Un error de servicio interno impidió que la solicitud se realizase correctamente. Vuelve a intentar realizar la solicitud.
ListingOptOutWarning El desarrollador quitó una descripción de un envío anterior o no incluyó la información de descripción que admitía el paquete.
ListingOptInWarning El desarrollador agregó una lista.
UpdateOnlyWarning El desarrollador está intentando insertar algo que solo presenta soporte técnico de actualizaciones.
Otros El envío presenta un estado no reconocido o sin clasificar.
PackageValidationWarning El proceso de validación del paquete genera una advertencia.