Poznawanie najlepszych rozwiązań dotyczących pól typu ciąg

Ten artykuł zawiera ogólne wskazówki dotyczące pól ciągów znaków w łączniku dla Microsoft Power Automate, Microsoft Power Apps, Microsoft Copilot Studio i Azure Logic Apps.

Informacje o łączniku

Ważne jest, aby podać podstawowe informacje o łączniku. Aby rozpocząć, postępuj zgodnie z podstawowymi wskazówkami opisanymi w tej sekcji. Nazwa łącznika znajduje się w polu tytuł. Opis łącznika znajduje się w polu _opis_. Oba pola pojawiają się w sekcji info w definicji OpenAPI (the apiDefinition.swagger.json file).

Oto kilka minimalnych wymagań, których należy przestrzegać w przypadku tytułów i opisów łączników:

• Tytuł łącznika może zawierać maksymalnie 30 znaków.
• Tytuł i opis łącznika nie mogą zawierać wyrazu API.
• Tytuł i opis łącznika nie mogą odwoływać się do żadnego innego Microsoft Copilot Studio produktu Microsoft Power Platform.
• Tytuł i opis łącznika nie mogą odwoływać się do produktu platformy ani produktu, dla którego użytkownik nie jest właścicielem interfejsów API zaplecza.

Więcej informacji na temat wytycznych dotyczących certyfikowanych łączników można znaleźć na stronie artykuł dotyczący składania certyfikatów. Zapoznaj się z nim, aby zapoznać się z najlepszymi praktykami.

Operacje

Każda ścieżka i czasownik w definicji interfejsu OpenAPI odpowiada operacji. Prawidłowe opisanie operacji w każdym z poniższych ciągów/tagów pomaga użytkownikowi końcowemu prawidłowo z niej korzystać. Oto kilka przykładów pól łańcuchowych dla operacji:

• podsumowanie: będzie wyświetlane jako nazwa operacji.

  • Sprawa: zdanie

  • Notatki:

    • W nazwie nie powinno być ukośnika („/”).
    • Nie może zawierać więcej niż 80 znaków.
    • Nie powinno kończyć się znakiem niealfanumerycznym, w tym znakiem interpunkcyjnym lub spacją.

• opis pojawia się jako opis operacji po wybraniu przycisku informacji. .

  • Sprawa: zdanie.
  • Uwagi: warto je skrócić w polu tekstowym. Nie jest wymagany okres, jeśli jest jeden wyraz.

• operationId: Jest to unikatowy identyfikator skojarzony z operacją.

  • Sprawa: Camel (bez spacji i interpunkcji).
  • Uwaga: Służy do zmiany znaczenia operacji, na przykład GetContacts lub CreateContact.

  Poniższy obrazek pokazuje, jak będą wyglądały pola summary - Wyślij wiadomość e-mail oraz description - Ta operacja wysyła wiadomość e-mail podczas tworzenia przepływu pracy.

  

Wyzwalacze a akcje

Wyzwalacz uruchamia przepływ pracy lub proces. Oto kilka przykładów:

• Uruchamianie przepływu pracy w każdy poniedziałek o 3 nad ranem
• Kiedy obiekt jest tworzony

Upewnij się, że pola podsumowania i opisu wyzwalacza są czytelne i mają znaczenie semantyczne. Podsumowanie wyzwalacza jest zazwyczaj wprowadzane w formacie: „Kiedy __________________”.

Przykład:

Opis wyzwalacza jest zwykle podany w formacie: „Ta operacja jest wyzwalana, gdy _______________”

Przykład:

• Ta operacja powoduje jest wyzwalana podczas dodawania nowego zadania.

Akcja jest zadaniem do wykonania w ramach przepływu pracy, takim jak Wyślij wiadomość e-mail, Aktualizuj wiersz, Wyślij powiadomienie itd. Oto kilka przykładów działania podsumowanie:

Parametry

Każda operacja (wyzwalacz lub akcja) ma parametry, które użytkownik podaje jako dane wejściowe. Oto niektóre z ważnych pól ciągów dla parametru:

• x-ms-summary: będzie wyświetlane jako nazwa parametru.

  • Sprawa: Tytuł
  • Uwagi: To pole znakowe ma limit 80 znaków

• opis: będzie on pokazywany jako opis parametru w polu wprowadzania.

  • Sprawa: zdanie
  • Uwagi: Opis powinien być krótki, aby zmieścił się w polu tekstowym. Nie jest wymagany okres, jeśli jest jeden wyraz.

  Na poniższej ilustracji wyróżniony parametr ma wartość Temat jako wartość pola x-ms-summary i Określ temat wiadomości e-mail jako wartość pola opis.

  

Response

Każda operacja ma odpowiedź, której można użyć później w przepływie pracy jako danych wejściowych kolejnej operacji. Schemat wyniku składa się z wielu właściwości. Oto niektóre z ważnych pól ciągów dla każdej właściwości to:

• x-ms-summary: będzie wyświetlane jako nazwa rezultatu właściwości.

  • Sprawa: Tytuł
  • Uwaga: Użyj krótkiej nazwy.

• opis: będzie wyświetlany jako opis właściwości wyniku.

  • Sprawa: zdanie
  • Uwagi: Opis powinien być krótki i zwięzły, z kropką na końcu.

  Na poniższym obrazie schemat wynikowy operacji Ręcznie wyzwalaj przepływ pojawia się podczas próby dodania zawartości dynamicznej w jednej z kolejnych operacji w przepływie pracy. W tym miejscu Adres e-mail użytkownika jest wartością pola x-ms-summary, a tekst pod nim jest wartością pola description dla właściwości w odpowiedzi operacji Wyzwól przepływ ręcznie.

Kilka ważnych uwag, które należy uwzględnić dla pól summary/x-ms-summary i opis:

• Tekst podsumowania i opisu nie powinien być taki sam.
• Opis powinien być używany w celu udostępnienia dodatkowych informacji dla użytkownika, takich jak format danych wyjściowych lub informacje o obiekcie, z którym właściwość jest powiązana. Na przykład: podsumowanie : identyfikator, opis: identyfikator użytkownika.
• W przypadku obiektu z zagnieżdżonymi wartościami pole x-ms-summary nazwy obiektu nadrzędnego zostanie dołączone do elementu podrzędnego.

Priorytet widoczności

Priorytet widoczności jednostki jest określony przez x-ms-visibility. Jeśli nie określono widoczności, przyjmowana jest widoczność „normalna”. Możliwe wartości to ważny, zaawansowany lub wewnętrzny. Jednostki oznaczone jako wewnętrzne nie są wyświetlane w interfejsie użytkownika.

Widoczność dotyczy:

• Operacje
• Parametry
• Właściwości odpowiedzi

Oto przykład:

Przykład: w interfejsie użytkownika jednostki oznaczone jako important są wyświetlane jako pierwsze, jednostki oznaczone jako zaawansowane są ukryte w przełączniku (wyróżnionym), natomiast elementy oznaczone jako wewnętrzne nie są wyświetlane. Poniższy obrazek jest przykładem domyślnego wyświetlania parametrów oznaczonych jako ważne. Pokazuje również parametry oznaczone jako zaawansowane, które są wyświetlane po wybraniu przycisku Pokaż opcje zaawansowane.

Przekazywanie opinii

Jesteśmy wdzięczni za opinie na temat problemów z platformą łączników oraz pomysły na nowe funkcje. Aby przekazać opinię, przejdź na stronę Przesyłanie problemów lub uzyskiwanie pomocy dotyczącej łączników i wybierz typ opinii.