Udostępnij za pośrednictwem

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

  • Artykuł

Poniższy artykuł zawiera ogólne wskazówki dotyczące pól ciągów w łączniku aplikacji Power Automate, Power Apps i Azure Logic Apps.

Informacje o łączniku

Każdemu łącznikowi powinien przypisany tytuł, czyli nazwa łącznika i opis, który zawiera ogólne informacje na jego temat. Te informacje powinny być określone w polach title i description w sekcji info w definicji interfejsu OpenAPI (w pliku apiDefinition.swagger.json).

W przypadku tytułów i opisów łączników należy przestrzegać co najmniej następujących wytycznych:

  • 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 produktu platformy Power Platform ani produktu, dla którego użytkownik nie jest właścicielem interfejsów API zaplecza.

Wyższy standard wytycznych dotyczących pól tytułów i opisów wymuszanych w przypadku certyfikowanych łączników można znaleźć tutaj i te wytyczne należy stosować jako najlepsze praktyki.

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 niektóre z pól ciągów 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ą.

  • description: się jako opis operacji po wybraniu przycisku informacyjnego Zrzut ekranu pokazujący przycisk informacyjny., jak pokazano na poniższym obrazku.

    • 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.

    Zrzut ekranu pokazujący, jak będą wyglądały pola podsumowania i opisu.

Wyzwalacze a akcje

Wyzwalacz uruchamia przepływ pracy lub proces. Na przykład „Uruchom przepływ pracy w każdy poniedziałek o godzinie 3:00”, „Po utworzeniu obiektu” itd.

Pola podsumowań i opisów wyzwalaczy powinny być odczytywane przez człowieka i mają znaczenie semantyczne. Podsumowanie wyzwalacza jest zazwyczaj wprowadzane w formacie: „Kiedy __________________”.

Przykład:

Wyzwalacz Podsumowanie
Utworzenie Kiedy zostanie utworzone zadanie
Zaktualizuj Kiedy zostanie aktualizowane zadanie
Usunięty Kiedy zostanie usunięte zadanie

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 tego podsumowania akcji:

Akcja Podsumowanie
Utworzenie Utwórz nowe zadanie
Czytaj Pobierz zadanie według identyfikatora
Zaktualizuj Aktualizuj obiekt
Usunięty Usuń obiekt
Lista Lista wszystkich obiektów

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ł
    • Uwaga: Nazwa ma limit długości równy 80 znaków

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

    • Sprawa: zdanie
    • Uwaga: warto je skrócić 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.

    Zrzut ekranu, który pokazuje wartości parametrów x-ms-summary i description w interfejsie.

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
    • Uwaga: 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 opis dla właściwości w odpowiedzi operacji „Wyzwól przepływ ręcznie”.

odpowiedź

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.

x-ms-visibility

Określa widoczność priorytetu jednostki. Jeśli nie określono widoczności, przyjmowana jest widoczność „normalna”. Możliwe wartości to „ważne”, „zaawansowane” lub „wewnętrzne”. Jednostki oznaczone jako „wewnętrzne” nie są wyświetlane w interfejsie użytkownika.

Dotyczy:

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

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.

Zrzut ekranu pokazujący listę rozwijaną dla opcji zaawansowanych.

Zrzut ekranu, który pokazuje rozwinięte zaawansowane opcje.

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.