Automatische AppSource-Übermittlung von Business Central-Apps

Ein Wunsch vieler Partner war, Apps automatisch von ihrem DevOps-Setup an die AppSource-Validierung senden zu können. Die Aufnahme-API für Partner Center unterstützt alle Angebotstypen in AppSource und kann verwendet werden, um Updates für Business Central-Apps an AppSource zu übermitteln.

Leider enthält die API nur sehr wenig Dokumentation und die spärliche Dokumentation enthält keine Informationen über Business Central. Wenn Sie die Dinge jedoch selbst untersuchen möchten, sind die wichtigsten Dokumente:

Anstatt die API zu beschreiben und alle Partner ihren eigenen Code erstellen zu lassen, um ihre Apps zu untersuchen und einzureichen, enthält der neueste BcContainerHelper (4.0.3) Funktionen, um genau dies zu tun, indem die Partner Center Ingestion API verwendet wird.

Authentifizierung

Um loszulegen, benötigen Sie eine Möglichkeit, sich bei der Partner Center-Erfassungs-API zu authentifizieren. Dies kann mithilfe der Dienst 2-Dienstauthentifizierung erfolgen (die für Workflows und Pipelines empfohlen wird) oder Sie können den Benutzeridentitätswechsel verwenden.

Dienst 2 Dienst (S2S)

Um mit S2S zu beginnen, müssen Sie Schritt 1 von hier aus ausführen: https://docs.microsoft.com/en-us/azure/marketplace/azure-app-apis. Danach sollten Sie eine ClientID und ein ClientSecret haben, die in einem KeyVault gespeichert sind, und die eigentliche Authentifizierung erfolgt über die New-BcAuthContext Funktion von BcContainerHelper:

$authcontext = New-BcAuthContext `
    -clientID ($PublisherAppClientIdSecret.SecretValue | Get-PlainText) `
    -clientSecret $PublisherAppClientSecretSecret.SecretValue `
    -Scopes "https://api.partner.microsoft.com/.default" `
    -TenantID ""

Identitätswechsel des Benutzers

Wenn Sie aus irgendeinem Grund keine AAD-App-Registrierung für die S2S-Authentifizierung erstellen können oder wollen, besteht die andere Option zum Abrufen eines Authentifizierungskontexts darin, den Benutzeridentitätswechsel zu verwenden.

$authcontext = New-BcAuthContext `
    -includeDeviceLogin `
    -Scopes "https://api.partner.microsoft.com/.default" `
    -tenantID ""

Dadurch wird der Gerätefluss aufgerufen und ein Code angezeigt, den Sie verwenden müssen, wenn Sie sich bei https://aka.ms/devicelogin authentifizieren

Jetzt haben Sie einen Authentifizierungskontext, der ein Zugriffstoken und ein Aktualisierungstoken enthält. Das Zugriffstoken kann in der Regel 60 Minuten lang zur Authentifizierung verwendet werden. Das Refreshtoken kann verwendet werden, um normalerweise 90 Tage lang ein neues Zugriffstoken zu erhalten, und Sie können das Refresh-Token in einem Schlüsseltresor speichern, um mithilfe dieses Codes einen neuen authContext basierend auf dem Refreshtoken zu erhalten:

$authcontext = New-BcAuthContext `
    -refreshToken $refreshtoken `
    -Scopes "https://api.partner.microsoft.com/.default" `
    -tenantID ""

AuthContext

Das $authContext muss für alle Funktionen angegeben werden und Sie sollten nie in den Auth-Kontext schauen müssen. Der Grund für das Herumtragen des AuthContext und nicht „nur“ eines AccessToken ist, dass das AccessToken nach 60 Minuten abläuft und Pipelines/Skripte/Tests häufig länger als 60 Minuten laufen. Aus diesem Grund enthält der AuthContext genügend Informationen, um das AccessToken zu erneuern, und alle Funktionen in ContainerHelper werden es überprüfen und bei Bedarf erneuern. Wenn Sie jemals einen Autorisierungsheader basierend auf dem AuthContext erstellen müssen, können Sie dies folgendermaßen tun:

$authContext = Renew-BcAuthContext -bcAuthContext $authContext 
$headers += @{ "Authorization" = "Bearer $($authcontext.AccessToken)" }

Aber auch hier ist dies für die folgenden Szenarien nicht erforderlich, der Authentifizierungskontext wird automatisch in allen Funktionen erneuert und verwendet entweder die ClientID und das ClientSecret oder das Aktualisierungstoken zum Erneuern.

Wenn Sie einen AuthContext haben, können Sie dies validieren, indem Sie Folgendes ausführen:

Get-AppSourceProduct -authContext $authcontext -silent

Und Sie sollten eine Liste aller Ihrer Apps in AppSource sehen.

Senden einer App an die AppSource-Validierung

Derzeit unterstützt die Partner Center-Erfassungs-API nicht das direkte Senden einer App an die Produktion. Sie müssen die Übermittlung nach der technischen Validierung bewerben (klicken Sie auf Go Live).

Das New-AppSourceSubmission Funktion enthält eine -autoPromote Parameter, der auf den Abschluss der technischen Validierung wartet und danach automatisch die Promotion-Aktion aufruft. Wenn die API unterstützt AutoPromoteändert sich das Innenleben der Funktion, um dies zu nutzen, anstatt zu warten.

Mit Ihrem AuthContext von oben können Sie alle Ihre Produkte erhalten, indem Sie Folgendes verwenden:

$products = Get-AppSourceProduct -authContext $authcontext -silent

und erhalten Sie die Produkt-ID des Produkts, mit dem Sie arbeiten möchten:

$productName="BingMaps.AppSource"
$productId = ($products | Where-Object { $_.name -eq $productName }).id

Wenn Sie alle Details des Produkts erhalten möchten, können Sie Folgendes verwenden:

$product = Get-AppSourceProduct -authContext $authcontext -productId $productId -includeAll

Jetzt können Sie die Eigenschaften von $product überprüfen. Beispiele:

$product.FeatureAvailability[0].marketStates

marketCode state   
---------- -----   
AE         Disabled
AT         Disabled
AU         Disabled
BE         Disabled
CA         Disabled
CH         Disabled
CO         Disabled
CZ         Disabled
DE         Disabled
DK         Enabled 
EE         Disabled
ES         Disabled 
...
$product.Property

resourceType          : AzureProperty
industries            : {}
categories            : {}
additionalCategories  : {}
submissionVersion     : 
productTags           : {}
appVersion            : 3.0.164.0
useEnterpriseContract : False
termsOfUse            : The terms that applies to Microsoft Dynamics 365 Business Central can be downloaded here: 
                        https://www.microsoft.com/en-us/licensing/product-licensing/products.aspx 
                         
                        If you have signed up to the trial version of Microsoft Dynamics 365 Business Central with an organizational email address, you are governed by the Microsoft 
                        Online Service Trial Agreement, which can be found here: https://go.microsoft.com/fwlink/?linkid=828977 
extendedProperties    : {}
hideKeys              : {}
applicableProducts    : {}
marketingOnlyChange   : False
globalAmendmentTerms  : 
customAmendments      : {}
leveledIndustries     : 
leveledCategories     : @{geolocation=System.Object[]}
@odata.etag           : "0800a065-0000-0800-0000-62ee043a0000"
id                    : 009f7479-f506-216f-d445-5315d5fb9e62

Sie können auch Informationen über Ihre letzte Einreichung erhalten, indem Sie Folgendes verwenden:

Get-AppSourceSubmission -authContext $authcontext -productId $productId -includeWorkflowDetails
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695125040
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695125040/workflowdetails

resourceType       : Submission
state              : Published
substate           : InStore
targets            : {@{type=Scope; value=Preview}}
resources          : {@{type=Availability; value=4b8c7499-1cb3-acf6-9b5b-c45d2a7040e2}, @{type=Listing; value=0202f16e-e12b-a657-124e-27ed76542ad5}, @{type=Package; 
                     value=2d212b32-f3f4-4d43-ac9b-5783f7a6099f}, @{type=Property; value=ae0f3f9e-b893-bbde-4dd1-3ac0b50496ef}...}
publishedTimeInUtc : 2022-08-04T13:53:31.2590809Z
pendingUpdateInfo  : @{updateType=Create; status=Completed}
releaseNumber      : 28
friendlyName       : Submission 28
areResourcesReady  : True
id                 : 1152921505695125040
WorkflowDetails    : {@{type=Push; state=Success; targetEnvironment=Preview; workflowSteps=System.Object[]; startDateTimeInUtc=2022-08-04T10:37:37.4038218; 
                     completeDateTimeInUtc=2022-08-04T10:51:26.8132496}, @{type=Push; state=Success; targetEnvironment=Live; workflowSteps=System.Object[]; 
                     startDateTimeInUtc=2022-08-04T10:51:57.0499235; completeDateTimeInUtc=2022-08-04T13:53:30.8277395}}

Der Zustand/Unterzustand Ihrer Übermittlung kann die folgenden Werte haben:

  • Veröffentlicht/InStore – Ihre Einreichung wurde veröffentlicht und das Angebot ist in AppSource verfügbar
  • In Bearbeitung/Eingereicht – Ihre Einreichung wurde eingereicht und die Validierung läuft (während dieser Phase kann Ihre Einreichung abgebrochen werden)
  • Veröffentlicht/Bereit zur Veröffentlichung – Ihr Beitrag befindet sich in der Vorschau und kann beworben/ live geschaltet werden. Zu diesem Zeitpunkt können Sie eine neue Einreichung erstellen, wenn Sie diese Version nicht live schalten möchten.
  • ?/? – Ihre Einreichung befindet sich in der Zertifizierungs-/Veröffentlichungsphase. Diese Phase kann nicht abgebrochen werden und Sie können keine neue Einreichung erstellen, bis Ihre App veröffentlicht wurde.

Sie können eine Übermittlung auch während der Ausführung mit der Funktion Get-AppSourceSubmission überwachen:

$submission = Get-AppSourceSubmission -authContext $authcontext -productId $productId -includeWorkflowDetails
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860/workflowdetails

PS C:> $submission.WorkflowDetails

type                  : Push
state                 : InProgress
targetEnvironment     : Preview
workflowSteps         : {@{name=Automated validation; state=Success; startDateTimeInUtc=2022-08-06T06:38:53.8153199; completeDateTimeInUtc=2022-08-06T06:42:08.3546437}, 
                        @{name=Preview Creation; state=Success; startDateTimeInUtc=2022-08-06T06:42:11.2274863; completeDateTimeInUtc=2022-08-06T06:47:30.8841703}, @{name=Publisher 
                        Signoff; state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
startDateTimeInUtc    : 2022-08-06T06:37:47.6696794
completeDateTimeInUtc : 0001-01-01T00:00:00

type                  : Push
state                 : NotStarted
targetEnvironment     : Live
workflowSteps         : {@{name=Certification; state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}, @{name=Publish; 
                        state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
startDateTimeInUtc    : 0001-01-01T00:00:00
completeDateTimeInUtc : 0001-01-01T00:00:00

Die workflowDetails sind ein Array, bestehend aus zwei PSCustomObjects. Das erste sind die Details zur Vorschau (vor dem Drücken der Go Live-Schaltfläche) und das zweite sind die Details zum Go Live (nach dem Drücken der Go Live-Schaltfläche). Etwas später sehen die workflowDetails so aus:

$submission = Get-AppSourceSubmission -authContext $authcontext -productId $productId -includeWorkflowDetails
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860/workflowdetails

PS C:> $submission

resourceType       : Submission
state              : Published
substate           : ReadyToPublish
targets            : {@{type=Scope; value=Preview}}
resources          : {@{type=Availability; value=a179fdd3-9950-5235-493d-ffe6dd02b4aa}, @{type=Listing; value=280ae301-a6ca-293c-88b3-8b49cfe58480}, @{type=Package; 
                     value=6ba6a084-9bba-4c3c-8eae-cea773809696}, @{type=Property; value=009f7479-f506-216f-d445-5315d5fb9e62}...}
publishedTimeInUtc : 2022-08-06T06:47:36.5830633Z
pendingUpdateInfo  : @{updateType=Create; status=Completed}
releaseNumber      : 29
friendlyName       : Submission 29
areResourcesReady  : True
id                 : 1152921505695131860
WorkflowDetails    : {@{type=Push; state=Success; targetEnvironment=Preview; workflowSteps=System.Object[]; startDateTimeInUtc=2022-08-06T06:37:47.6696794; 
                     completeDateTimeInUtc=2022-08-06T06:47:35.721944}, @{type=Push; state=NotStarted; targetEnvironment=Live; workflowSteps=System.Object[]; 
                     startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
type                  : Push
state                 : Success
targetEnvironment     : Preview
workflowSteps         : {@{name=Automated validation; state=Success; startDateTimeInUtc=2022-08-06T06:38:53.8153199; completeDateTimeInUtc=2022-08-06T06:42:08.3546437}, 
                        @{name=Preview Creation; state=Success; startDateTimeInUtc=2022-08-06T06:42:11.2274863; completeDateTimeInUtc=2022-08-06T06:47:30.8841703}, @{name=Publisher 
                        Signoff; state=Success; startDateTimeInUtc=2022-08-06T06:47:32.6862082; completeDateTimeInUtc=2022-08-06T06:47:35.721944}}
startDateTimeInUtc    : 2022-08-06T06:37:47.6696794
completeDateTimeInUtc : 2022-08-06T06:47:35.721944

type                  : Push
state                 : NotStarted
targetEnvironment     : Live
workflowSteps         : {@{name=Certification; state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}, @{name=Publish; 
                        state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
startDateTimeInUtc    : 0001-01-01T00:00:00
completeDateTimeInUtc : 0001-01-01T00:00:00

Das bedeutet, dass die Benutzeroberfläche Ihres Partnercenters wie folgt aussieht:

Und Sie können drücken Geh Leben (oder laufe Promote-AppSourceSubmission), um die App live zu schalten (oder eine Zertifizierung / Marketingvalidierung aufzurufen)

New-AppSourceSubmission

In diesem Zustand können Sie eine neue Version zur Validierung übermitteln – Sie müssen die Übermittlung nicht live schalten. Das Einreichen einer neuen Version Ihrer App erfolgt über die New-AppSourceSubmission Funktionen:

New-AppSourceSubmission -authContext $authContext -productId $product.Id -appFile $appFile -silent
Extracting C:UsersfreddykDownloadsBingMaps.AppSource-main-Apps-3.0.164.0Freddy Kristiansen_BingMaps.AppSource_3.0.164.0.app
Automated validation........ Success
Preview Creation.......... Success
Publisher Signoff Success
New AppSource submission succeeded

resourceType       : Submission
state              : Published
substate           : ReadyToPublish
targets            : {@{type=Scope; value=Preview}}
resources          : {@{type=Availability; value=553dfb07-1fe0-6e19-a136-cf6f310127b4}, @{type=Listing; value=383dfff3-5479-dba7-7480-f61f3022ecfd}, @{type=Package; 
                     value=141ca192-e27b-4529-be55-f96de1e1710d}, @{type=Property; value=86c43c9b-6184-ff69-4621-a644cc167977}...}
publishedTimeInUtc : 2022-08-06T07:26:10.2335664Z
pendingUpdateInfo  : @{updateType=Create; status=Completed}
releaseNumber      : 31
friendlyName       : Submission 31
areResourcesReady  : True
id                 : 1152921505695131645

Wenn Sie die einbeziehen -autoPromote kennzeichnen, wartet die Funktion und befördert die Übermittlung automatisch in die Produktion/Go Live. Wenn Sie die einbeziehen warte nicht Flag, wartet die Funktion nicht auf den Abschluss. Wenn Sie die einbeziehen autoPromote Und die warte nicht Flag, die Funktion wird (in der aktuellen Version) warte immer noch damit die Erstellung der Vorschau abgeschlossen werden kann, und bewerben Sie dann die Einreichung. Für eine spätere Version der API (when IsAutoPromote wird für Business Central Apps unterstützt) wird die Funktion neu geschrieben, um die API-Unterstützung von autoPromote zu nutzen, anstatt zu warten und die API erneut aufzurufen.

Dies bedeutet auch, dass, wenn Sie die Funktion abbrechen, während Sie auf den Abschluss der Vorschau warten – die autoPromote Flagge hat keine Wirkung.

Wenn Sie angeben –LibraryAppFiles das New-AppSourceSubmission, können Sie ein Array von Dateien angeben. Wenn Sie nur eine Datei angeben, wird sie unverändert in Partner Center hochgeladen. Wenn Sie ein Array von Dateien angeben, werden sie zusammen in eine Datei mit demselben Namen wie die angegebene AppFile gezippt, gefolgt von .libraries.zipwas bedeutet, dass Sie das Komprimieren selbst vornehmen müssen, wenn Sie den Dateinamen steuern möchten.

Wenn Ihre Übermittlung fehlschlägt, können Sie die Fehlermeldung im Portal sehen. Derzeit habe ich keine Möglichkeit gefunden, die Fehlermeldung über die API zu erhalten. Ich habe eine Frage an das Team gestellt und erwarte, bald mehr zu erfahren (und den Code zu ändern).

Genießen

Freddie Kristiansen
Technischer Evangelist

.

Author: admin

Leave a Reply

Your email address will not be published.