Compartir a través de

Administrar envíos de remesas de paquetes

La API de envío de Microsoft Store proporciona métodos que puedes usar para administrar vuelos de paquetes para tus aplicaciones, incluidas las implementaciones graduales. 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 vuelo de paquetes, asegúrate de hacer más cambios en el envío exclusivamente a través de 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 gestionar envíos de paquetes de vuelo

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

Método URI Descripción
OBTENER https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Obtener una presentación de vuelo de paquete existente
OBTENER https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status Obtener el estado de un envío de paquete de lanzamiento existente
PUBLICACIÓN https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions Crear un nuevo envío de vuelo de paquete
PON https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Actualizar un envío de vuelo de paquete existente
PUBLICACIÓN https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit Realizar una nueva o actualizada presentación de vuelo de paquete
ELIMINAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Eliminar un envío de vuelo de paquete

Crear un envío de paquete por vuelo

Para crear una presentación para un paquete de vuelo, siga este proceso.

  1. Si aún no lo ha hecho, complete los requisitos previos descritos 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 del identificador y la clave de cliente. Sólo tienes que hacer esto una vez; después de tener el identificador y la clave de cliente, puede reutilizarlos en cualquier momento que necesite crear un nuevo token de acceso de Azure AD.

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

  3. Crear 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 de vuelo que incluye el identificador del nuevo envío, el URI de firma de acceso compartido (SAS) para subir paquetes al Azure Blob Storage para el envío, 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 de SAS y firmas de acceso compartido, parte 2: Creación y uso de una SAS con Blob Storage.

  4. Si usted está agregando nuevos paquetes para la entrega, prepare los paquetes y agréguelos a un archivo ZIP.

  5. Revise el envío de piloto datos 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 la entrega, cargue el archivo ZIP en Azure Blob Storage mediante el URI de SAS que se te proporcionó en el cuerpo de la respuesta del método POST que usaste anteriormente. Hay diferentes bibliotecas de Azure que puede usar para hacerlo en una variedad de plataformas, entre las que se incluyen:

    En el ejemplo de código de C# siguiente 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. Comprometer el envío del paquete de vuelo ejecutando el siguiente método. Esto avisará al Centro de asociados que ha completado su envío y que las actualizaciones deben aplicarse ahora a su cuenta.

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

  8. Compruebe el estado del commit ejecutando el método siguiente para obtener el estado de la remesa de paquete.

    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 del estado en el cuerpo de la respuesta. Este valor debe cambiar de CommitStarted a PreProcessing si la solicitud tiene éxito o a CommitFailed si hay errores en la solicitud. Si hay errores, el campo statusDetails contiene más detalles sobre el error.

  9. Una vez completado correctamente el commit, el envío se envía a la tienda para el procesamiento. Puedes seguir supervisando el progreso del envío mediante 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 de PowerShell 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 forma principal de enviar muchas aplicaciones de primera entidad a la Tienda.

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

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

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 de forma programática el despliegue gradual de un paquete en un envío piloto, siga este procedimiento utilizando los métodos de la API de envío de Microsoft Store:

  1. Crear un envío de vuelo de paquete o obtener un envío de vuelo de paquete.
  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 actualizar un envío de paquete piloto.

Una vez habilitado un despliegue gradual de paquetes para un envío de vuelo de paquete, puedes usar los métodos siguientes para obtener, actualizar, detener o finalizar el despliegue gradual programáticamente.

Método URI Descripción
OBTENER https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout Obtener la información de implementación gradual de un envío de paquete
PUBLICACIÓN 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
PUBLICACIÓN 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
PUBLICACIÓN 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.

Recurso para el envío de vuelos

Este recurso describe una presentación de paquete de vuelo.

{
  "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.

Importancia Tipo Descripción
identificación cuerda / cadena Identificador del envío.
flightId cuerda / cadena Identificador del vuelo de paquete al que está asociado el envío.
estado cuerda / cadena Estado del envío. Este puede ser uno de los siguientes valores:
  • Ninguno
  • Cancelado
  • CompromisoPendiente
  • CommitStarted
  • Falló el commit
  • Pendiente de publicación
  • Publicación
  • Publicado
  • Error de publicación
  • Preprocesamiento
  • Error en el preprocesamiento
  • Certificación
  • Fallo de certificación
  • Versión
  • Lanzamiento fallido
detalles del estado objeto Un estado detalla el recurso que contiene detalles adicionales sobre el estado del envío, incluida la información sobre los errores.
flightPackages arreglo Contiene recursos del paquete de vuelo que proporcionan detalles sobre cada paquete del envío.
opcionesDeEntregaDePaquetes objeto Un recurso de opciones de entrega de paquetes que contiene el despliegue gradual de paquetes y las opciones de actualización obligatoria para la presentación.
fileUploadUrl cuerda / cadena URI de firma de acceso compartido (SAS) para subir paquetes para la presentación. Si va a agregar nuevos paquetes para el envío, cargue el archivo ZIP que contiene los paquetes a este URI. Para obtener más información, consulta Crear una propuesta de vuelo de paquete.
modoDePublicaciónObjetivo cuerda / cadena Modo de publicación de la presentación. Este puede ser uno de los siguientes valores:
  • Inmediata
  • Manual de instrucciones
  • FechaEspecífica
fechaObjetivoDePublicación cuerda / cadena La fecha de publicación del envío en formato ISO 8601, si el modo de publicación objetivo (targetPublishMode) está establecido en una fecha específica (SpecificDate).
notasParaCertificación cuerda / cadena 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 las 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.

Importancia Tipo Descripción
Errores objeto Conjunto de recursos de detalles de estado que contienen detalles de error de la presentación.
Advertencias objeto Conjunto de recursos de detalles de estado que contienen detalles de advertencia para la presentación.
informes de certificación objeto Conjunto de recursos relacionados con el informe de certificación que proporcionan acceso a los datos del informe de certificación para la presentación. Puede examinar estos informes para obtener más información si se produce un error en la certificación.

Recurso detallado de estado

Este recurso proporciona información adicional sobre cualquier error o advertencia relacionada con una presentación. Este recurso tiene los siguientes valores.

Importancia Tipo Descripción
código cuerda / cadena Código de estado de envío que describe el tipo de error o advertencia.
Detalles cuerda / cadena Mensaje con más detalles sobre el problema.

Informe de certificación de recursos

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

Importancia Tipo Descripción
fecha cuerda / cadena Fecha y hora en que se generó el informe, en formato ISO 8601.
URL de informe cuerda / cadena Dirección URL en la que puede acceder al informe.

Recurso de paquete de vuelo

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 actualización de envío de paquete piloto, solo los valores de fileName, fileStatus, minimumDirectXVersiony mínimoSystemRam de este objeto son necesarios en el cuerpo de la solicitud. Los demás valores serán rellenados por el Centro de Partners.

Importancia Tipo Descripción
Nombre del archivo cuerda / cadena Nombre del paquete.
estado del archivo cuerda / cadena Estado del paquete. Este puede ser uno de los siguientes valores:
  • Ninguno
  • Carga pendiente
  • Subido
  • PendienteDelete
identificación cuerda / cadena Identificador que identifica de forma única el paquete. Este valor lo usa el Centro de partners.
Versión cuerda / cadena Versión del paquete de la aplicación. Para obtener más información, consulte numeración de versión del paquete.
arquitectura cuerda / cadena Arquitectura del paquete de la aplicación (por ejemplo, ARM).
Idiomas arreglo 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, consulte Idiomas compatibles.
Capacidades arreglo Matriz de funcionalidades requeridas por el paquete. Para obtener más información sobre las funcionalidades, consulte Declaraciones de funcionalidad de la aplicación.
versión mínima de DirectX cuerda / cadena 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:
  • Ninguno
  • DirectX93
  • DirectX100
memoriaRAMmínimaDelSistema cuerda / cadena La memoria RAM mínima que se requiere para 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:
  • Ninguno
  • Memory2GB

Recurso de opciones de entrega de paquetes

Este recurso contiene el despliegue gradual de paquetes y la configuración de actualización obligatoria para la presentación.

{
  "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.

Importancia Tipo Descripción
packageRollout objeto Un recurso de despliegue de paquetes que contiene la configuración de lanzamiento gradual del paquete para la presentación.
esActualizaciónObligatoria booleano Indica si quieres tratar los paquetes de esta remisión como obligatorios para la autoinstalación de actualizaciones de la aplicación. Para obtener más información sobre los paquetes obligatorios para las actualizaciones de aplicaciones autoinstalados, consulte Descargar e instalar actualizaciones de paquetes para la aplicación.
fechaEfectivaDeActualizaciónObligatoria fecha Fecha y hora en que los paquetes de este envío son obligatorios, en formato ISO 8601 y zona horaria UTC.

Recurso de despliegue de paquetes

Este recurso contiene ajustes de implementación gradual de paquetes para la presentación. Este recurso tiene los siguientes valores.

Importancia Tipo Descripción
isPackageRollout booleano Indica si el despliegue gradual de paquetes está habilitado para el envío.
porcentajeDeDespliegueDelPaquete flotante Porcentaje de usuarios que recibirán los paquetes en el lanzamiento gradual.
estado de despliegue del paquete cuerda / cadena Una de las siguientes cadenas que indica el estado del lanzamiento gradual de los paquetes:
  • DespliegueDelPaqueteNoIniciado
  • DespliegueDelPaqueteEnProgreso
  • Despliegue del Paquete Completado
  • DespliegueDePaqueteDetenido
fallbackSubmissionId cuerda / cadena Identificador del envío que recibirán los clientes que no obtengan los paquetes de lanzamiento gradual.

Nota:

El packageRolloutStatus y el fallbackSubmissionId son valores que se asignan mediante el Centro de Socios, y no están destinados a ser establecidos por el desarrollador. Si incluye estos valores en un cuerpo de la solicitud, se omitirán estos valores.

Enumeraciones

Estos métodos usan 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
Ninguno No se especificó ningún código.
ArchivoInválido 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 mostraron en los datos de envío o se encuentran en la ubicación incorrecta del archivo.
ErrorDeValidacionDelPaquete No se pudo validar uno o varios paquetes del envío.
Valor de Parámetro No Válido Uno de los parámetros del cuerpo de la solicitud no es válido.
Operación no válida La operación que intentó no es válida.
Estado inválido La operación que intentó no es válida para el estado actual del paquete de vuelo.
RecursoNoEncontrado No se encontró el paquete de vuelo especificado.
Error de servicio Un error interno del servicio impedía que la solicitud se realizara correctamente. Vuelva a intentar la solicitud.
Advertencia de exclusión de listado El desarrollador quitó un listado de un envío anterior o no incluyó información de listado admitida por el paquete.
Advertencia para unirse a la lista El desarrollador agregó una lista.
UpdateOnlyWarning El desarrollador está intentando insertar algo que solo tenga compatibilidad con actualizaciones.
Otros El envío está en un estado no reconocido o no clasificado.
AdvertenciaDeValidaciónDePaquete El proceso de validación del paquete produjo una advertencia.