API-Automatisierer

UFO unterstützt derzeit die Verwendung des Win32 API API-Automator, um mit der nativen API der Anwendung zu interagieren. Wir implementieren diese in Python mithilfe der pywin32 Bibliothek. Der API-Automator unterstützt derzeit Word und Excel Anwendungen, und wir arbeiten daran, die Unterstützung auf weitere Anwendungen auszudehnen.

Konfiguration

Es gibt mehrere Konfigurationen, die vor der Verwendung des API-Automators in der Datei config_dev.yaml eingerichtet werden müssen. Nachfolgend finden Sie die Liste der Konfigurationen, die sich auf den API-Automator beziehen.

Konfigurationsoption Beschreibung Typ Standardwert
USE_APIS Ob die Verwendung von Anwendungs-APIs erlaubt sein soll. Boolean True
APP_API_PROMPT_ADDRESS Die Prompt-Adresse für die Anwendungs-API. Dict {"WINWORD.EXE": "ufo/prompts/apps/word/api.yaml", "EXCEL.EXE": "ufo/prompts/apps/excel/api.yaml", "msedge.exe": "ufo/prompts/apps/web/api.yaml", "chrome.exe": "ufo/prompts/apps/web/api.yaml"}

Hinweis

Nur WINWORD.EXE und EXCEL.EXE werden derzeit vom API-Automator unterstützt.

Empfänger

Die Basisklasse für den Empfänger des API-Automators ist die Klasse WinCOMReceiverBasic, die im Modul ufo/automator/app_apis/basic definiert ist. Sie wird mit dem Win32 COM-Objekt der Anwendung initialisiert und bietet Funktionalitäten zur Interaktion mit der nativen API der Anwendung. Nachfolgend finden Sie die Referenz für die Klasse WinCOMReceiverBasic.

Basiert auf: ReceiverBasic

Die Basisklasse für Windows COM-Clients.

Initialisiert den Windows COM-Client.

Parameter
  • app_root_name (str) –

    Der Stammname der Anwendung.

  • process_name (str) –

    Der Prozessname.

  • clsid (str) –

    Die CLSID des COM-Objekts.
Quellcode in automator/app_apis/basic.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(self, app_root_name: str, process_name: str, clsid: str) -> None:
    """
    Initialize the Windows COM client.
    :param app_root_name: The app root name.
    :param process_name: The process name.
    :param clsid: The CLSID of the COM object.
    """

    self.app_root_name = app_root_name
    self.process_name = process_name

    self.clsid = clsid

    self.client = win32com.client.Dispatch(self.clsid)
    self.com_object = self.get_object_from_process_name()

full_path property

Ruft den vollständigen Pfad des Prozesses ab.

Rückgabe
  • str –

    Der vollständige Pfad des Prozesses.

app_match(object_name_list)

Prüft, ob der Prozessname mit dem Anwendungsstamm übereinstimmt.

Parameter
  • object_name_list (List[str]) –

    Die Liste der Objektnamen.
Rückgabe
  • str –

    Der übereinstimmende Objektnamen.
Quellcode in automator/app_apis/basic.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def app_match(self, object_name_list: List[str]) -> str:
    """
    Check if the process name matches the app root.
    :param object_name_list: The list of object name.
    :return: The matched object name.
    """

    suffix = self.get_suffix_mapping()

    if self.process_name.endswith(suffix):
        clean_process_name = self.process_name[: -len(suffix)]
    else:
        clean_process_name = self.process_name

    if not object_name_list:
        return ""

    return max(
        object_name_list,
        key=lambda x: self.longest_common_substring_length(clean_process_name, x),
    )

close()

Schließt die Anwendung.

Quellcode in automator/app_apis/basic.py 
110
111
112
113
114
115
116
117
def close(self) -> None:
    """
    Close the app.
    """
    try:
        self.com_object.Close()
    except:
        pass

get_object_from_process_name() abstractmethod

Ruft das Objekt anhand des Prozessnamens ab.

Quellcode in automator/app_apis/basic.py 
36
37
38
39
40
41
@abstractmethod
def get_object_from_process_name(self) -> win32com.client.CDispatch:
    """
    Get the object from the process name.
    """
    pass

get_suffix_mapping()

Ruft die Suffix-Zuordnung ab.

Rückgabe
  • Dict[str, str] –

    Die Suffix-Zuordnung.
Quellcode in automator/app_apis/basic.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
def get_suffix_mapping(self) -> Dict[str, str]:
    """
    Get the suffix mapping.
    :return: The suffix mapping.
    """
    suffix_mapping = {
        "WINWORD.EXE": "docx",
        "EXCEL.EXE": "xlsx",
        "POWERPNT.EXE": "pptx",
        "olk.exe": "msg",
    }

    return suffix_mapping.get(self.app_root_name, None)

longest_common_substring_length(str1, str2) staticmethod

Ruft die längste gemeinsame Teilzeichenkette zweier Zeichenketten ab.

Parameter
  • str1 (str) –

    Die erste Zeichenkette.

  • str2 (str) –

    Die zweite Zeichenkette.
Rückgabe
  • int –

    Die Länge der längsten gemeinsamen Teilzeichenkette.
Quellcode in automator/app_apis/basic.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
@staticmethod
def longest_common_substring_length(str1: str, str2: str) -> int:
    """
    Get the longest common substring of two strings.
    :param str1: The first string.
    :param str2: The second string.
    :return: The length of the longest common substring.
    """

    m = len(str1)
    n = len(str2)

    dp = [[0] * (n + 1) for _ in range(m + 1)]

    max_length = 0

    for i in range(1, m + 1):
        for j in range(1, n + 1):
            if str1[i - 1] == str2[j - 1]:
                dp[i][j] = dp[i - 1][j - 1] + 1
                if dp[i][j] > max_length:
                    max_length = dp[i][j]
            else:
                dp[i][j] = 0

    return max_length

save()

Speichert den aktuellen Zustand der Anwendung.

Quellcode in automator/app_apis/basic.py 
91
92
93
94
95
96
97
98
def save(self) -> None:
    """
    Save the current state of the app.
    """
    try:
        self.com_object.Save()
    except:
        pass

save_to_xml(file_path)

Speichert den aktuellen Zustand der Anwendung in XML.

Parameter
  • file_path (str) –

    Der Dateipfad zum Speichern der XML-Datei.
Quellcode in automator/app_apis/basic.py 
100
101
102
103
104
105
106
107
108
def save_to_xml(self, file_path: str) -> None:
    """
    Save the current state of the app to XML.
    :param file_path: The file path to save the XML.
    """
    try:
        self.com_object.SaveAs(file_path, self.xml_format_code)
    except:
        pass

Die Empfänger für Word und Excel Anwendungen erben von der Klasse WinCOMReceiverBasic. Die Klassen WordReceiver und ExcelReceiver sind in den Modulen ufo/automator/app_apis/word bzw. ufo/automator/app_apis/excel definiert.

Befehl

Der Befehl des API-Automators für die Anwendungen Word und Excel befindet sich im Modul client im Ordner ufo/automator/app_apis/{app_name} und erbt von der Klasse WinCOMCommand. Er kapselt die Funktion und Parameter, die zur Ausführung der Aktion erforderlich sind. Nachfolgend finden Sie ein Beispiel für eine WordCommand Klasse, die von der Klasse SelectTextCommand erbt.

@WordWinCOMReceiver.register
class SelectTextCommand(WinCOMCommand):
    """
    The command to select text.
    """

    def execute(self):
        """
        Execute the command to select text.
        :return: The selected text.
        """
        return self.receiver.select_text(self.params.get("text"))

    @classmethod
    def name(cls) -> str:
        """
        The name of the command.
        """
        return "select_text"

Hinweis

Die konkreten Befehlsklassen müssen die Methode execute zur Ausführung der Aktion und die Methode name zur Rückgabe des Namens des atomaren Befehls implementieren.

Hinweis

Jeder Befehl muss mit einem konkreten WinCOMReceiver registriert werden, um ausgeführt zu werden. Dies geschieht über den Dekorator register.

Nachfolgend finden Sie die Liste der verfügbaren Befehle im API-Automator, die derzeit von UFO unterstützt werden.

Word API Befehle

Befehlsname Funktionsname Beschreibung
InsertTableCommand insert_table Fügt eine Tabelle in ein Word-Dokument ein.
SelectTextCommand select_text Wählt den Text in einem Word-Dokument aus.
SelectTableCommand select_table Wählt eine Tabelle in einem Word-Dokument aus.

Excel API Befehle

Befehlsname Funktionsname Beschreibung
GetSheetContentCommand get_sheet_content Ruft den Inhalt eines Blattes in der Excel-Anwendung ab.
Table2MarkdownCommand table2markdown Konvertiert den Tabelleninhalt in einem Blatt der Excel-Anwendung in das Markdown-Format.
InsertExcelTableCommand insert_excel_table Fügt eine Tabelle in das Excel-Blatt ein.

Tipp

Bitte beachten Sie die Datei ufo/prompts/apps/{app_name}/api.yaml für die Prompt-Details zu den Befehlen.

Tipp

Sie können die Befehle anpassen, indem Sie neue Befehlsklassen zum Modul ufo/automator/app_apis/{app_name}/ hinzufügen.