Udostępnij za pośrednictwem

Przygotowanie plików łącznika Power Platform i dodatków plug-in do certyfikacji

  • Artykuł

Ten proces dotyczy zweryfikowanych wydawców (z wykluczeniem wydawców niezależnych).

Po zakończeniu opracowywania łącznika niestandardowego postępuj zgodnie z poniższymi krokami, aby przygotować go do certyfikacji i wygenerować pliki łącznika do przesłania do Microsoft.

Uwaga

W tym temacie zamieszczono informacje na temat certyfikowania łączników niestandardowych w usługach Azure Logic Apps, Power Automate, Power Apps i dodatków w Copilot. Przed rozpoczęciem kroków opisanych w tym artykule przeczytaj Uzyskaj certyfikowany łącznik.

Krok 1: Zarejestruj łącznik i/lub dodatek plug-in (dotyczy tylko niezależnych wydawców)

Ta sekcja nie dotyczy zweryfikowanych wydawców.

Opracowywanie łącznika niestandardowego nie musi być zakończone, aby przesłać prośbę o certyfikację. Aby rozpocząć proces certyfikacji, zarejestruj łącznik w celu uzyskania certyfikatu, wypełniając formularz rejestracji.

Oczekując na wiadomość e-mail w ciągu dwóch dni roboczych od kontaktu firmy Microsoft, który:

  • Rozumie niestandardowy łącznik, łącznik i/lub dodatek plug-in.
  • Sprawdzi, jaki jest postęp opracowywania.
  • Przeprowadzi Cię przez proces certyfikacji.

Krok 2. Spełnianie wymagań dotyczących łączników

Aby zachować wysoką jakość i spójność naszych certyfikowanych łączników, firma Microsoft ma zestaw wymagań i wskazówek, jakie musi spełniać łącznik niestandardowy na potrzeby certyfikacji.

Nadawanie łącznikowi tytułu

Twój tytuł musi spełniać następujące wymagania.

  • Musi istnieć i być napisany w języku angielskim.
  • Musi być unikatowy i odróżniany od istniejącego tytułu łącznika.
  • Powinien być nazwą produktu lub organizacji.
  • Powinien być zgodny z istniejącymi wzorcami nazewnictwa dla certyfikowanych łączników i/lub dodatków. W przypadku niezależnych wydawców nazwa oprogramowania sprzęgającego powinna być zgodna ze wzorcem Connector and/or plugin Name (Independent Publisher).
  • Nie może być dłuższy niż 30 znaków.
  • Nie może zawierać słów API, Connector ani żadnej nazwy naszych produktów Power Platform (np. Power Apps).
  • Nie może zakończyć się znakiem innym niż alfanumerycznym, na przykład powrót karetki, nowy wiersz lub puste miejsce.

Przykłady

  • Dobre tytuły łączników i/lub dodatków plug-in: Azure Sentinel*, *Office 365 Outlook
  • Niedobre tytuły łączników i/lub dodatków plug-in: Azure Sentinel's Power Apps Connector,Office 365 Outlook API

Pisanie opisu łącznika

Opis musi spełnić następujące wymagania.

  • Musi istnieć i być napisany w języku angielskim.
  • Nie może zawierać błędów gramatycznych ani błędów pisowni.
  • Powinien opisywać zwięźle cel i wartość oferowaną przez łącznik.
  • Nie może być krótszy niż 30 znaków lub dłuższy niż 500 znaków.
  • Nie może zawierać żadnej nazwy produktów Power Platform (na przykład „Power Apps”).

Projektowanie ikony łącznika (dotyczy tylko sprawdzonych wydawców)

Ta sekcja nie dotyczy niezależnych wydawców.

  • Utwórz Logo o rozmiarze 1:1 w zakresie od 100 x 100 do 230 × 230 pikseli (bez zaokrąglenia rogów).
  • Użyj nieprzezroczystego, nie białego koloru tła (#ffffff) i nie domyślnego koloru (#007ee5) dopasowania do określonego koloru w tle ikony.
  • Upewnij się, że ikona jest unikatowa w stosunku do każdej innej ikony certyfikowanego łącznika.
  • Prześlij logo w formacie PNG jako <icon>.png.
  • Dzięki temu można ustawić rozmiar logo o rozmiarze poniżej 70% dla wysokości obrazu & szerokości spójnego tle.
  • Upewnij się, że kolor marki jest prawidłowym kolorem w kodzie szesnastkowym i nie powinien być biały (#ffffff) ani domyślny (#007ee5).

Definiowanie podsumowań i opisów operacji i parametrów

Opisy i podsumowania muszą spełnić następujące wymagania.

  • Musi istnieć i być napisany w języku angielskim.
  • Nie może zawierać błędów gramatycznych ani błędów pisowni.
  • Podsumowania operacji i parametrów powinny składać się z fraz, nie więcej niż 80 znaków i zawierać tylko znaki alfanumeryczne lub nawiasy.
  • Opisy operacji i parametrów powinny być pełnymi, opisowymi zdaniami i kończyć się interpunkcją.
  • Nie mogą zawierać żadnej nazwy produktów Microsoft Power Platform (na przykład „Power Apps”).

Definiowanie dokładnych odpowiedzi na operację

Odpowiedzi operacji muszą spełnić następujące wymagania.

  • Zdefiniuj odpowiedzi operacji z dokładnym schematem tylko z oczekiwanymi odpowiedziami.
  • Nie używaj odpowiedzi domyślnych z dokładną definicją schematu.
  • Podaj prawidłowe definicje schematu odpowiedzi dla wszystkich operacji w swaggerze.
  • Nie są dozwolone puste schematy odpowiedzi z wyjątkiem sytuacji, gdy schemat odpowiedzi jest dynamiczny. Oznacza to, że w danych wyjściowych nie jest dozwolona żadna zawartość dynamiczna, a twórcy muszą użyć języka JSON do analizy odpowiedzi.
  • Puste operacje są niedozwolone.
  • Należy usunąć puste właściwości, o ile nie są to wymagane.

Sprawdzanie właściwości struktury Swagger

Właściwości muszą spełnić następujące wymagania.

  • Upewnij się, że właściwość openapfinition jest w poprawnie sformatowanym pliku JSON.
  • Upewnij się, że definicja struktury Swagger jest zgodna ze standardem OpenAPI 2.0 i standardem rozszerzenia łącznika.

Zweryfikuj parametry połączenia

Parametry muszą spełnić następujące wymagania.

  • Upewnij się, że właściwość jest aktualizowana odpowiednimi wartościami „UIDefinition” (wyświetlana nazwa, opis).

  • Jeśli parametr połączenia używa uwierzytelniania podstawowego, należy upewnić się, że plik JSON jest poprawnie sformatowany jak w następującym przykładzie.

    {
  "username": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourUsernameLabel",
      "description": "The description of YourUsernameLabel for this api",
      "tooltip": "Provide the YourUsernameLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": true,
        "required": "true"
        }
  }
},
  "password": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourPasswordLabel",
      "description": "The description of YourPasswordLabel for this api",
      "tooltip": "Provide the YourPasswordLabel tooltip text",
      "constraints": {
        "tabIndex": 3,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Jeśli parametr połączenia używa klucza APIKey jako uwierzytelniania, należy upewnić się, że plik JSON jest poprawnie sformatowany jak w następującym przykładzie.

    {
  "api_key": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourApiKeyParameterLabel",
      "tooltip": "Provide your YourApiKeyParameterLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Jeśli parametr połączenia używa ogólnego OAuth jako uwierzytelniania, należy upewnić się, że plik JSON jest poprawnie sformatowany jak w następującym przykładzie.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "oauth2",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "AuthorizationUrl": {
          "value": "https://contoso.com"
        },
        "TokenUrl": {
          "value": "https://contoso.com"
        },
        "RefreshUrl": {
          "value": "https://contoso.com"
        }
      },
      "clientId": "YourClientID"
    },
    "uiDefinition": null
  }
}

  • Jeśli parametr połączenia ma dostawcę tożsamości OAuth2, należy upewnić się, że dostawca tożsamości znajduje się na liście obsługiwanych dostawców uwierzytelniania OAuth2. Poniżej przedstawiono przykład GitHub jako dostawcy tożsamości OAuth2:

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "github",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {},
      "clientId": "YourClientId"
    },
    "uiDefinition": null
  }
}

  • Jeśli parametr połączenia używa tożsamości Microsoft Entra jako uwierzytelniania, należy upewnić się, że plik JSON jest poprawnie sformatowany jak w następującym przykładzie.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "aad",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "LoginUri": {
          "value": "https://login.microsoftonline.com"
        },
        "TenantId": {
          "value": "common"
        },
        "ResourceUri": {
          "value": "resourceUri"
        },
        "EnableOnbehalfOfLogin": {
          "value": false
        }
      },
      "clientId": "AzureActiveDirectoryClientId"
    },
    "uiDefinition": null
  }
}

Tworzenie wysokiej jakości ciągów znaków w języku angielskim

Łączniki są lokalizowane w ramach lokalizacji Power Automate; dlatego podczas tworzenia łącznika jakość angielskich ciągów znaków jest kluczowa dla jakości tłumaczenia. Oto kilka głównych obszarów, na których można się skoncentrować podczas tworzenia wartości ciągów.

  • Upewnij się, że wykorzystasz program sprawdzający pisownię, aby upewnić się, że wszystkie wartości łańcuchowe są wolne od literówek. Jeśli istnieje niekompletny angielski ciąg znaków, wynik tłumaczenia jest niekompletny lub zawiera błędy w kontekście.

  • Upewnij się, że zdanie jest w pełnej formie. Jeśli zdanie nie jest pełne, może to również generować niższą jakość tłumaczeń.

  • Upewnij się, że znaczenie zdania jest jasne. Jeśli znaczenie zdania jest niejednoznaczne, może to również generować niższą jakość lub niepoprawne tłumaczenia.

  • Upewnij się, że streszczenia, x-ms-summaries i opisy są poprawne gramatycznie. Nie kopiuj ich i nie wklejaj. Aby dowiedzieć się, jak są wyświetlane w produkcie, przejdź do Wskazówki dotyczące ciągów łącznika.

  • Jeśli to możliwe, unikaj złożonych ciągów znaków w czasie wykonywania. Zamiast tego używaj w pełni ukształtowanych zdań. Złożone ciągi lub zdania utrudniają tłumaczenie lub mogą spowodować błędne tłumaczenie.

  • Jeśli używasz skrótów, upewnij się, że piszesz je wielkimi literami, aby było to jasne. Zmniejsza to ryzyko pomyłek w przypadku błędu typograficznego.

  • Ciągi w formacie CaMel (na przykład mnimizeHighways or MinimizeHighways) są zwykle traktowane jako niemożliwe do przetłumaczenia. Jeśli chcesz zlokalizowane wartości tego typu ciągu, należy naprawić ciąg formularza CaMel.

Krok 3: Uruchamianie sprawdzania rozwiązania, aby zweryfikować poprawności łącznika

Sprawdzanie rozwiązania to mechanizm wykonujący analizy statyczne, aby upewnić się, że łącznik jest zgodny ze standardami wymaganymi przez firmę Microsoft do certyfikacji. Dodaj łącznik do rozwiązania w Power Automate lub Power Apps i uruchom sprawdzanie rozwiązania zgodnie z instrukcjami w Weryfikuj poprawności łącznika niestandardowego przy użyciu sprawdzania rozwiązania.

Obejrzyj to wideo, aby dowiedzieć się, jak uruchomić sprawdzanie rozwiązania!

Krok 4. Dodawanie metadanych

Artefakty łącznika (pliki) muszą zawierać określone metadane opisujące łącznik i jego usługę końcową. Informacje zawarte w metadanych są publikowane w dokumentacji łącznika i są publicznie dostępne dla wszystkich użytkowników. Nie należy udostępniać informacji prywatnych i poufnych oraz skontaktować się z firmą Microsoft w przypadku jakichkolwiek problemów z dostarczeniem do firmy Microsoft tych informacji. Aby dowiedzieć się, jak są dokumentowane metadane, odwiedź jedną ze stron dokumentacji specyficznych dla łącznika w sekcji Informacje o łączniku.

Krok 4a: właściwości publisher i stackOwner

  • publisher to nazwa firmy lub organizacji użytkownika. Wprowadź pełną nazwę firmy (na przykład „Contoso Corporation”). Musi być w formacie alfanumerycznym.
  • "stackOwner to firma lub organizacja będąca właścicielem stosu zaplecza, z którym jest połączony łącznik. Musi być w formacie alfanumerycznym.
Wydawca Description Przykład
Zweryfikowano Wydawca i stackOwner są tacy sami, chyba że deweloper ISV tworzy łącznik w imieniu strony stackOwner. "wydawca": "Tesla",
"stackOwner": "Tesla"
Niezależny Należy podać właściciela wykresu i właściciela wydawcy. "wydawca": "Nirmal Kumar",
"stackOwner": "ITGlue"

Lokalizacja pliku: apiProperties.json
Aby dowiedzieć się więcej, zobacz Plik właściwości interfejsu API.

Składnia: Właściwości Wydawca i stackOwner występują jako właściwości najwyższego poziomu w pliku apiProperties.json. Dodaj następujące wyróżnione wiersze w przedstawiony sposób. Upewnij się, że podałeś nazwę właściwości i schemat dokładnie tak, jak pokazano na rysunku.

Zrzut ekranu pokazujący właściwości publisher i stackOwner, które są dostępne w przykładowych stawkach kodu

Krok 4c: przykładowe fragmenty kodu

Możesz użyć następujących wstawek kodu, aby skopiować i wprowadzić swoje informacje. Upewnij się, że dodajesz wstawki do odpowiednich plików w odpowiednich lokalizacjach, jak opisano w poprzednim rozdziale.

    "publisher": "_____",
    "stackOwner": "_____"

    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }

    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

Uwaga

Istnieje bieżące ograniczenie użycia właściwości stackOwner i naszego narzędzia interfejsu wiersza użytkownika Paconn. Więcej informacji można znaleźć w sekcji Ograniczenia w pliku README.

Krok 4d: Formatowanie i ograniczenia plików JSON

  • Upewnij się, że właściwości są poprawnie wyrównane.

  • Wklej kod JSON do Visual Studio Code. Możesz używać rozszerzeń, takich jak sprawdzania pisowni oraz dodatków plug-in JSON.

  • Rozmiar plików rozłożenia nie powinien być większy niż 1 MB.

    • Rozważ wygląd łącznika przed rozpoczęciem jego tworzenia. Oceniać, czy łącznik powinien zostać przerwany na dwa (2) łączniki, czy więcej.
    • Większe pliki rozsyłania mogą powodować opóźnienie używania łącznika.

    Na platformie znajdują się na przykład trzy (3) różne łączniki usługi HubSpot.

    Zrzut ekranu folderów dla trzech łączników usługi HubSpot.

Krok 4e: Weryfikacja poprawności niestandardowych plików łączników

Uruchom program paconn validate --api-def [Location of apiDefinition.swagger.json]. To narzędzie weryfikuje definicję łącznika i informuje o błędach, które należy naprawić przed przesłaniem.

Jeśli łącznik używa standardu OAuth jako typu uwierzytelniania, należy dodać te dozwolone adresy URL przekierowania do aplikacji:

  • https://global.consent.azure-apim.net/redirect/{apiname}

  • https://global-test.consent.azure-apim.net/redirect/{apiname}

Krok 5. Spełnianie wymagań dotyczących dodatków

Ta sekcja ma zastosowanie, jeśli przesyłasz także skojarzony dodatek plug-in connector do certyfikatów.

Krok 6: Przygotowanie łącznika i/lub artefaktów dodatków plug-in

Uwaga

  • Upewnij się, że postępowałeś zgodnie ze specyfikacjami i zapewniłeś jakość swojego łącznika i/lub dodatku przed certyfikacją. Niezastosowanie się do tego spowoduje opóźnienia w certyfikacji, ponieważ zostaniesz poproszony o wprowadzenie zmian.
  • Podaj produkcyjną wersję adresu URL hosta. Przemieszczania, tworzenia i testowania adresów URL hosta nie są dozwolone.

Do Microsoft należy przesłać zestaw plików zwanych artefaktami łącznika, które pobiera się przy użyciu narzędzia interfejsu wiersza polecenia (CLI) dostarczanego przez Microsoft. To narzędzie weryfikuje poprawność łącznika pod kątem wystąpienia wszelkich błędów.

Wkonaj następujące kroki, aby rozpocząć:

  1. Zainstaluj narzędzie interfejsu wiersza polecenia łączników platformy Microsoft Power Platform zgodnie z instrukcjami dotyczącymi instalacji.

  2. Zaloguj się do Microsoft Power Platform, korzystając z wiersza polecenia i uruchamiając polecenie paconn login. Postępuj zgodnie z instrukcjami, aby zalogować się za pomocą procesu kodu urządzenia firmy Microsoft.

  3. Po uwierzytelnieniu się, pobierz pliki niestandardowych konektorów:

    • Uruchom program paconn download. Wybierz środowisko, w którym znajduje się łącznik niestandardowy, określając jego numer w wierszu polecenia, a następnie wybierz nazwę łącznika niestandardowego.

    Narzędzie pobierze artefakty łącznika i/lub dodatku w folderze do lokalizacji systemowej plików, w której uruchomiono paconn. W zależności od typu wydawcy można znaleźć różne artefakty:

Przewodnik dotyczący pakowania łącznika i dodatku

Procedury w tej sekcji przewodnik po różnych scenariuszach opakowań. Jeśli chcesz pakować tylko łącznik niestandardowy, użyj pierwszego scenariusza. Jeśli chcesz pakować tylko łącznik i dodatek niestandardowy, użyj pierwszego scenariusza. Jeśli chcesz pakować tylko istniejący łącznik i dodatek niestandardowy, użyj pierwszego scenariusza.

Pakowanie niestandardowego łącznika i przesyłanie do certyfikacji

  1. Tworzenie łączników niestandardowych w rozwiązaniach.

  2. Uruchom sprawdzanie rozwiązania w rozwiązaniu łącznik w kroku 1.

  3. Wyeksportuj rozwiązanie łącznika.

  4. Utwórz przepływ (testowanie) przy użyciu nowo utworzonego łącznika niestandardowego i dodaj przepływ do rozwiązania.

  5. Eksport rozwiązania przepływu.

  6. Tworzenie pakietu z rozwiązaniamiz kroków 3 i 5.

  7. Utwórz plik intro.mdintro.md.

  8. Ostatni pakiet należy utworzyć jako plik zip o następującym formacie:

    Zrzut ekranu folderów i plików w pliku zip, aby uzyskać certyfikat certyfikowanego łącznika.

  9. Przekaż pakiet do obiektu blob magazynu i wygeneruj adres URL sas.

  10. Prześlij do pakietu w Centrum partnerskim.

Pakowanie niestandardowego łącznika i dodatku oraz przesyłanie do certyfikacji

  1. Wykonaj kroki od 1 do 5 w pakiecie łącznika niestandardowego i prześlij do certyfikacji w tym artykule.

  2. Utwórz dodatek plug-in w Microsoft Copilot Studio portalu i wyeksportuj go jako rozwiązanie.

  3. Utwórz pakiet z następujących danych:

  4. Utwórz plik intro.mdintro.md.

  5. Ostatni pakiet należy utworzyć jako plik zip o następującym formacie.

    Zrzut ekranu folderów i plików w pliku zip, aby uzyskać certyfikat certyfikowanego łącznika i dodatku.

Pakowanie istniejącego zweryfikowanego łącznika i dodatku oraz przesyłanie do certyfikacji

  1. Utwórz rozwiązanie w Power Automatei dodaj do niego już certyfikowany łącznik.

  2. Wykonaj kroki od 2 do 4 w pakiecie łącznika niestandardowego i prześlij do certyfikacji w tym artykule.

  3. Utwórz dodatek plug-in w Copilot Studio i wyeksportuj go jako rozwiązanie.

  4. Wyeksportuj dodatek jako rozwiązanie.

  5. Utwórz pakiet z następujących danych:

  6. Utwórz plik intro.mdintro.md.

  7. Ostatni pakiet należy utworzyć jako plik zip o następującym formacie.

    Zrzut ekranu folderów i plików w pliku zip, aby uzyskać certyfikat certyfikowanego łącznika i dodatku.

Zarówno sprawdzeni wydawcy, jak i wydawcy niezależni pobierają apiProperties.json w ich artefaktach. W tym pliku należy ustawić wartość IconBrandColor.

  • Sprawdzeni wydawcy: Ustaw iconBrandColor na kolor swojej marki w pliku apiProperties.
  • Niezależni wydawcy: Ustaw iconBrandColor na „#da3b01” w pliku apiProperties.
    Zrzut ekranu żywej pomarańczowej ikony (da3b01).

Utwórz artefakt intro.md.

Plik intro.md jest niezbędny zarówno dla niezależnych wydawców, jak i zweryfikowanych wydawców. Należy utworzyć plik intro.md w celu udokumentowania funkcji i funkcjonalności łącznika. Przykład dokumentacji, która ma być dołączyć, przejdź do przykładu Readme.md. Aby dowiedzieć się więcej o pisaniu pliku intro.md, zapoznaj się z innymi plikami intro.md (znanymi też jako Readme.md) w repozytorium TychSom.

Jeśli jesteś niezależnym wydawcą, a łącznik używa OAuth, upewnij się, że masz instrukcje uzyskiwania poświadczeń.

Porada

Znane problemy i ograniczenia to doskonały punkt do podtrzymywania aktualnych informacji dla użytkowników.

Krok 7: Przesyłanie łącznika i/lub dodatku do certyfikacji

W trakcie tego procesu będziesz przesyłać swój łącznik i/lub dodatek jako oprogramowanie open source do naszego repozytorium łączników Microsoft Power Platform.

  1. (Dla wydawców niezależnych) Aby przesłać pakiet do firmy Microsoft w celu uzyskania certyfikatów, należy postępować zgodnie z instrukcjami podanymi w procesie certyfikacji niezależnego wydawcy.

  2. (Dla wydawców certyfikowanych) Aby przesłać pakiet do firmy Microsoft do Centrum Partnerskiego w celu uzyskania certyfikatów, należy postępować zgodnie z instrukcjami podanymi w procesie certyfikacji niezależnego wydawcy.

    Jeśli jesteś sprawdzonym wydawcą i używasz kodu niestandardowego, musisz przesłać plik script.csx.

    Jeśli łącznik ma już adres OAuth, należy podać identyfikator klienta oraz informacje o partnerze w Centrum partnerskim. Ponadto należy uzyskać nazwę API z żądania przesyłania łącznika w celu zaktualizowania aplikacji.

    W ramach przekazywania danych firma Microsoft certyfikuje dodatek i/lub łącznik. Aby rozwiązać problemy z błędami rozsyłania, przejdź do tematu Naprawianie błędów validatora oprogramowania Swagger.

Lista kontrolna przed przesłaniem

Przed przejściem do przesyłania łącznika do certyfikacji przez Microsoft upewnij się, że:

Porada

  • Twórz filmy, blogi lub inne treści w serwisie YouTube, aby udostępniać próbki lub zrzuty ekranu, aby rozpocząć korzystanie z łącznika i/lub dodatku.
    • Dołącz łącza do pliku intro.md, aby można było dodać je do dokumentów.
  • Dodaj podpowiedzi do swojego pliku swaggera, aby pomóc użytkownikom osiągnąć większy sukces.

Następny krok