Управление отправками надстроек

  • Статья

API отправки в Microsoft Store предоставляет методы, которые можно использовать для управления отправкой надстроек (также известных как веб-приложение или IAP) для приложений. Общие сведения об API отправки Microsoft Store, включая предварительные требования для использования API, см. в статье "Создание отправки и управление ими с помощью служб Microsoft Store".

Важно!

Если вы используете API отправки Microsoft Store для создания отправки надстройки, обязательно внесите дальнейшие изменения только с помощью API, а не вносить изменения в Центр партнеров. Если вы используете Центр партнеров для изменения отправки, созданной с помощью API, вы больше не сможете изменить или зафиксировать эту отправку с помощью API. В некоторых случаях отправка может оставаться в состоянии ошибки, в которой она не может продолжаться в процессе отправки. В этом случае необходимо удалить отправку и создать новую отправку.

Методы управления отправкой надстроек

Используйте следующие методы, чтобы получить, создать, обновить, зафиксировать или удалить отправку надстройки. Прежде чем использовать эти методы, надстройка должна уже существовать в учетной записи Центра партнеров. Вы можете создать надстройку в Центре партнеров, определив его тип продукта и идентификатор продукта или используя методы API отправки Microsoft Store, описанные в разделе "Управление надстройками".

Method URI Description
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Получение существующей отправки надстроек
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status Получение состояния существующей отправки надстройки
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions Создание отправки надстроек
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Обновление существующей отправки надстройки
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit Фиксация новой или обновленной отправки надстройки
DELETE https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Удаление отправки надстройки

Создание отправки надстроек

Чтобы создать отправку для надстройки, выполните этот процесс.

  1. Если вы еще не сделали этого, выполните предварительные требования, описанные в статье "Создание отправки и управление ими с помощью служб Microsoft Store", включая связывание приложения Azure AD с учетной записью Центра партнеров и получение идентификатора клиента и ключа. Это нужно сделать только один раз; После того как у вас есть идентификатор клиента и ключ, их можно повторно использовать в любое время, когда необходимо создать новый маркер доступа Azure AD.

  2. Получите маркер доступа Azure AD. Этот маркер доступа необходимо передать методам в API отправки Microsoft Store. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера можно получить новый.

  3. Выполните следующий метод в API отправки Microsoft Store. Этот метод создает новую выполняющуюся отправку, которая является копией последней опубликованной отправки. Дополнительные сведения см. в разделе "Создание отправки надстройки".

    POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions

    Текст ответа содержит ресурс отправки надстройки, содержащий идентификатор новой отправки, универсальный код ресурса (URI) подписанного URL-адреса (SAS) для отправки всех значков надстройки для отправки в Хранилище BLOB-объектов Azure, а также все данные для новой отправки (например, списки и сведения о ценах).

    Примечание.

    URI SAS предоставляет доступ к защищенному ресурсу в службе хранилища Azure, не требуя ключей учетной записи. Общие сведения о URI SAS и их использовании с Хранилище BLOB-объектов Azure см. в разделе "Подписанные URL-адреса", часть 1. Общие сведения о модели SAS и подписанных URL-адресах, часть 2. Создание и использование SAS с хранилищем BLOB-объектов.

  4. Если вы добавляете новые значки для отправки, подготовьте значки и добавьте их в ZIP-архив.

  5. Обновите данные отправки надстроек с любыми необходимыми изменениями для новой отправки и выполните следующий метод, чтобы обновить отправку. Дополнительные сведения см. в разделе "Обновление отправки надстройки".

    PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}

    Примечание.

    Если вы добавляете новые значки для отправки, обязательно обновите данные отправки, чтобы ссылаться на имя и относительный путь к этим файлам в ZIP-архиве.

  6. Если вы добавляете новые значки для отправки, отправьте ZIP-архив в Хранилище BLOB-объектов Azure с помощью URI SAS, предоставленного в тексте ответа метода POST, который вы вызвали ранее. Существуют различные библиотеки Azure, которые можно использовать для этого на различных платформах, в том числе:

    В следующем примере кода C# показано, как отправить ZIP-архив в Хранилище BLOB-объектов Azure с помощью класса CloudBlockBlob в клиентской библиотеке служба хранилища Azure для .NET. В этом примере предполагается, что ZIP-архив уже записан в объект потока.

    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. Зафиксируйте отправку, выполнив следующий метод. При этом центр партнеров будет оповещен о том, что вы выполнили отправку и что обновления теперь должны применяться к вашей учетной записи. Дополнительные сведения см. в разделе "Фиксация отправки надстройки".

    POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit

  8. Проверьте состояние фиксации, выполнив следующий метод. Дополнительные сведения см. в разделе "Получение состояния отправки надстройки".

    GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status

    Чтобы подтвердить состояние отправки, просмотрите значение состояния в тексте ответа. Это значение должно измениться с CommitStarted на предварительную обработку, если запрос выполнен успешно или на CommitFailed, если в запросе возникают ошибки. Если возникают ошибки, поле statusDetails содержит дополнительные сведения об ошибке.

  9. После успешного завершения фиксации отправка отправляется в Магазин для приема. Вы можете продолжать отслеживать ход отправки с помощью предыдущего метода или посетить Центр партнеров.

Примеры кода

В следующих статьях приведены подробные примеры кода, демонстрирующие создание отправки надстроек на нескольких разных языках программирования:

Модуль StoreBroker PowerShell

В качестве альтернативы вызову API отправки Microsoft Store напрямую мы также предоставляем модуль PowerShell с открытым исходным кодом, который реализует интерфейс командной строки на вершине API. Этот модуль называется StoreBroker. Этот модуль можно использовать для управления отправкой приложений, полетов и надстроек из командной строки, а не вызова API отправки Microsoft Store напрямую, или вы можете просто просмотреть источник, чтобы просмотреть дополнительные примеры вызова этого API. Модуль StoreBroker активно используется в Корпорации Майкрософт в качестве основного способа отправки многих сторонних приложений в Магазин.

Дополнительные сведения см . на странице StoreBroker на сайте GitHub.

Ресурсы данных

Методы API отправки Microsoft Store для управления отправкой надстроек используют следующие ресурсы данных JSON.

Ресурс отправки надстройки

Этот ресурс описывает отправку надстройки.

{
  "id": "1152921504621243680",
  "contentType": "EMagazine",
  "keywords": [
    "books"
  ],
  "lifetime": "FiveDays",
  "listings": {
    "en": {
      "description": "English add-on description",
      "icon": {
        "fileName": "add-on-en-us-listing2.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (English)"
    },
    "ru": {
      "description": "Russian add-on description",
      "icon": {
        "fileName": "add-on-ru-listing.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (Russian)"
    }
  },
  "pricing": {
    "marketSpecificPricings": {
      "RU": "Tier3",
      "US": "Tier4",
    },
    "sales": [],
    "priceId": "Free",
    "isAdvancedPricingModel": true
  },
  "targetPublishDate": "2016-03-15T05:10:58.047Z",
  "targetPublishMode": "Immediate",
  "tag": "SampleTag",
  "visibility": "Public",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [
      {
        "code": "None",
        "details": "string"
      }
    ],
    "warnings": [
      {
        "code": "ListingOptOutWarning",
        "details": "You have removed listing language(s): []"
      }
    ],
    "certificationReports": [
      {
      }
    ]
  },
  "fileUploadUrl": "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",
  "friendlyName": "Submission 2"
}

Этот ресурс имеет следующие значения.

Значение Тип Описание
id строка Идентификатор отправки. Этот идентификатор доступен в данных ответа для запросов на создание отправки надстроек, получение всех надстроек и получение надстройки. Для отправки, созданной в Центре партнеров, этот идентификатор также доступен в URL-адресе страницы отправки в Центре партнеров.
contentType строка Тип содержимого , предоставленного в надстройке. Это может быть одно из следующих значений:
  • NotSet
  • BookDownload
  • EMagazine
  • ENewspaper
  • MusicDownload
  • MusicStream
  • OnlineData служба хранилища
  • VideoDownload
  • VideoStream
  • Asp
  • OnlineDownload
ключевые слова array Массив строк, содержащих до 10 ключевое слово для надстройки. Приложение может запрашивать надстройки с помощью этих ключевое слово.
lifetime строка Время существования надстройки. Это может быть одно из следующих значений:
  • Постоянно
  • OneDay
  • ThreeDays
  • FiveDays
  • OneWeek
  • TwoWeeks
  • OneMonth
  • TwoMonths
  • ТриMonths
  • ШестьMonths
  • OneYear
Предложения объект Словарь пар "ключ и значение", где каждый ключ — это двухбуквенный код страны ISO 3166-1 alpha-2, и каждое значение — это ресурс перечисления, содержащий сведения о списке для надстройки.
цены объект Ресурс ценообразования, содержащий сведения о ценах для надстройки.
targetPublishMode строка Режим публикации для отправки. Это может быть одно из следующих значений:
  • Интерпретация
  • Руководство
  • SpecificDate
targetPublishDate строка Дата публикации для отправки в формате ISO 8601, если targetPublishMode имеет значение SpecificDate.
тег строка Пользовательские данные разработчика для надстройки (эта информация ранее называлась тегом).
видимость строка Видимость надстройки. Это может быть одно из следующих значений:
  • Скрыт
  • Общедоступные
  • Личные
  • NotSet
статус строка Состояние отправки. Это может быть одно из следующих значений:
  • нет
  • Отмененные
  • ОжиданиеCommit
  • CommitStarted
  • CommitFailed
  • Ожидание публикации
  • Публикуется
  • Опубликованные
  • PublishFailed
  • Предварительной обработки
  • PreProcessingFailed
  • Сертификация
  • CertificationFailed
  • Выпуск
  • ReleaseFailed
statusDetails объект Ресурс сведений о состоянии, содержащий дополнительные сведения о состоянии отправки, включая сведения об ошибках.
fileUploadUrl строка URI подписанного URL-адреса (SAS) для отправки пакетов для отправки. Если вы добавляете новые пакеты для отправки, отправьте ZIP-архив, содержащий пакеты в этот URI. Дополнительные сведения см. в разделе "Создание отправки надстройки".
friendlyName строка Понятное имя отправки, как показано в Центре партнеров. Это значение создается при создании отправки.

Перечисление ресурса

Этот ресурс содержит сведения о списке для надстройки. Этот ресурс имеет следующие значения.

Значение Тип Описание
description строка Описание описания надстройки.
значок объект Ресурс значка, содержащий данные для значка для списка надстроек.
title string Заголовок списка надстроек.

Ресурс значка

Этот ресурс содержит данные значка для перечисления надстроек. Этот ресурс имеет следующие значения.

Значение Тип Описание
fileName строка Имя файла значка в ZIP-архиве, отправленном для отправки. Значок должен быть PNG-файлом, который измеряет ровно 300 x 300 пикселей.
fileStatus строка Состояние файла значка. Это может быть одно из следующих значений:
  • нет
  • ОжиданиеUpload
  • Отправка
  • ОжиданиеDelete

Ресурс ценообразования

Этот ресурс содержит сведения о ценах для надстройки. Этот ресурс имеет следующие значения.

Значение Тип Описание
marketSpecificPricings объект Словарь пар "ключ и значение", где каждый ключ — это двухбуквенный код страны ISO 3166-1 alpha-2, а каждое значение — ценовая категория. Эти элементы представляют пользовательские цены для вашей надстройки на определенных рынках. Все элементы в этом словаре переопределяют базовую цену, указанную значением priceId для указанного рынка.
продажи array Устарело. Массив ресурсов продажи, содержащих сведения о продажах для надстройки.
priceId строка Ценовая категория , указывающая базовую цену надстройки.
isAdvancedPricingModel boolean Если верно, ваша учетная запись разработчика имеет доступ к расширенному набору ценовых категорий с 99 долларов США до 1999,99 ДОЛЛ. США. Если значение false, ваша учетная запись разработчика имеет доступ к исходному набору ценовых категорий с 99 долл. США до 999,99 долл. США. Дополнительные сведения о разных уровнях см. в разделе ценовых категорий.

Обратите внимание, что это поле доступно только для чтения.

Ресурс продажи

Эти ресурсы содержат сведения о продаже надстройки.

Важно!

Ресурс Продажи больше не поддерживается, и в настоящее время вы не можете получить или изменить данные продажи для отправки надстройки с помощью API отправки Microsoft Store. В будущем мы обновим API отправки Microsoft Store, чтобы создать новый способ программного доступа к данным о продажах для отправки надстроек.

  • После вызова метода GET для получения отправки надстройки значение продаж будет пустым. Вы можете продолжать использовать Центр партнеров для получения данных о продажах для отправки надстройки.
  • При вызове метода PUT для обновления отправки надстройки данные в значении продаж игнорируются. Вы можете продолжать использовать Центр партнеров для изменения данных о продажах для отправки надстройки.

Этот ресурс имеет следующие значения.

Значение Тип Description
name строка Имя продажи.
basePriceId строка Ценовая категория , используемая для базовой цены продажи.
startDate строка Дата начала продажи в формате ISO 8601.
endDate строка Дата окончания продажи в формате ISO 8601.
marketSpecificPricings объект Словарь пар "ключ и значение", где каждый ключ — это двухбуквенный код страны ISO 3166-1 alpha-2, а каждое значение — ценовая категория. Эти элементы представляют пользовательские цены для вашей надстройки на определенных рынках. Все элементы в этом словаре переопределяют базовую цену, указанную значением basePriceId для указанного рынка.

Ресурс сведений о состоянии

Этот ресурс содержит дополнительные сведения о состоянии отправки. Этот ресурс имеет следующие значения.

Значение Тип Описание
ошибки объект Массив ресурсов сведений о состоянии, содержащих сведения об ошибке для отправки.
warnings объект Массив ресурсов сведений о состоянии, содержащих сведения о предупреждении для отправки.
certificationReports объект Массив ресурсов отчета о сертификации, предоставляющих доступ к данным отчета о сертификации для отправки. Эти отчеты можно просмотреть для получения дополнительных сведений, если сертификация завершается ошибкой.

Ресурс сведений о состоянии

Этот ресурс содержит дополнительные сведения о любых связанных ошибках или предупреждениях для отправки. Этот ресурс имеет следующие значения.

Значение Тип Описание
кодом строка Код состояния отправки, описывающий тип ошибки или предупреждения.
details строка Сообщение с дополнительными сведениями о проблеме.

Ресурс отчета о сертификации

Этот ресурс предоставляет доступ к данным отчета о сертификации для отправки. Этот ресурс имеет следующие значения.

Значение Тип Описание
Дата строка Дата и время создания отчета в формате ISO 8601.
reportUrl строка URL-адрес, по которому можно получить доступ к отчету.

Перечисления

Эти методы используют следующие перечисления.

Ценовые категории

Следующие значения представляют доступные ценовые категории в ресурсе ценовых ресурсов для отправки надстройки.

значение Описание
База Ценовая категория не задана; используйте базовую цену для надстройки.
NotAvailable Надстройка недоступна в указанном регионе.
Бесплатно Надстройка бесплатна.
Уровеньxxxx Строка, указывающая ценовую категорию для надстройки, в формате tierxxxx. В настоящее время поддерживаются следующие диапазоны ценовых категорий:

  • Если значение isAdvancedPricingModelресурса ценообразования имеет значение true, доступные значения ценовой категории для вашей учетной записи : Tier1012 - Tier1424.
  • Если значение isAdvancedPricingModel ресурса ценообразования равно false, доступные значения ценовой категории для вашей учетной записи — Tier2 - Tier96.
Чтобы просмотреть полную таблицу ценовых категорий, доступных для вашей учетной записи разработчика, включая рыночные цены, связанные с каждым уровнем, перейдите на страницу цен и доступности для любой из отправки приложений в Центре партнеров и щелкните ссылку на таблицу просмотра в разделе "Рынки" и пользовательские цены (для некоторых учетных записей разработчиков, эта ссылка находится в разделе "Цены").

Код состояния отправки

Следующие значения представляют код состояния отправки.

значение Описание
Нет Код не указан.
InvalidArchive ZIP-архив, содержащий пакет, является недопустимым или имеет нераспознанный формат архива.
MissingFiles ZIP-архив не содержит все файлы, которые были указаны в данных отправки, или они находятся в неправильном расположении в архиве.
PackageValidationFailed Не удалось проверить один или несколько пакетов в отправке.
InvalidParameterValue Один из параметров в тексте запроса недопустим.
InvalidOperation Предпринята недопустимая операция.
InvalidState Предпринятая операция недопустима для текущего состояния тестового пакета.
ResourceNotFound Не удалось найти указанный тест пакета.
ServiceError Внутренняя ошибка службы предотвратила успешное выполнение запроса. Повторите запрос.
ЛистингOptOutWarning Разработчик удалил список из предыдущей отправки или не включал сведения о списке, поддерживаемые пакетом.
ЛистингOptInWarning Разработчик добавил описание.
UpdateOnlyWarning Разработчик пытается вставить то, что поддерживает только обновления.
Другие Отправка находится в нераспознанном или некатегоризованном состоянии.
PackageValidationWarning Процесс проверки пакета привел к предупреждению.