Externe API-Anruf Unterstützung in Office-Skripts

  • Artikel

Skripts unterstützen Aufrufe externer Dienste. Verwenden Sie diese Dienste, um Ihrer Arbeitsmappe Daten und andere Informationen zur Verfügung zu stellen.

Achtung

Externe Aufrufe können dazu führen, dass vertrauliche Daten für unerwünschte Endpunkte verfügbar gemacht werden. Ihr Administrator kann Information Rights Management (IRM) oder Firewallschutz gegen solche Aufrufe einrichten.

Wichtig

Aufrufe externer APIs können nur über die Excel-Anwendung erfolgen, nicht über Power Automate unter normalen Umständen. Externe Aufrufe werden auch für Skripts, die auf einer SharePoint-Website gespeichert sind, nicht unterstützt.

Konfigurieren Ihres Skripts für externe Aufrufe

Externe Aufrufe sind asynchron und erfordern, dass Ihr Skript als asyncgekennzeichnet ist. Fügen Sie der main Funktion das async Präfix hinzu, und geben Sie ein Promisezurück, wie hier gezeigt:

async function main(workbook: ExcelScript.Workbook) : Promise <void>

Hinweis

Skripts, die andere Informationen zurückgeben, können einen Promise dieses Typs zurückgeben. Wenn Ihr Skript beispielsweise ein Employee -Objekt zurückgeben muss, lautet die Rückgabesignatur : Promise <Employee>

Sie müssen die Schnittstellen des externen Diensts kennenlernen, um Aufrufe an diesen Dienst zu tätigen. Wenn Sie oder REST-APIs verwendenfetch, müssen Sie die JSON-Struktur der zurückgegebenen Daten bestimmen. Erwägen Sie, sowohl für die Eingabe als auch für die Ausgabe ihres Skripts eine interface zu erstellen, die den erforderlichen JSON-Strukturen entspricht. Dies bietet dem Skript mehr Typsicherheit. Ein Beispiel hierfür finden Sie unter Verwenden von Abrufvorgängen aus Office-Skripts.

Einschränkungen bei externen Aufrufen von Office-Skripts

  • Es gibt keine Möglichkeit, sich anzumelden oder den OAuth2-Typ von Authentifizierungsflows zu verwenden. Alle Schlüssel und Anmeldeinformationen müssen hartcodiert sein (oder aus einer anderen Quelle gelesen werden).
  • Es gibt keine Infrastruktur zum Speichern von API-Anmeldeinformationen und -schlüsseln. Dies muss vom Benutzer verwaltet werden.
  • Dokumentcookies, localStorage- und sessionStorage -Objekte werden nicht unterstützt.
  • Externe Aufrufe können dazu führen, dass vertrauliche Daten für unerwünschte Endpunkte verfügbar gemacht werden oder externe Daten in interne Arbeitsmappen gebracht werden. Ihr Administrator kann einen Firewallschutz gegen solche Aufrufe einrichten. Überprüfen Sie unbedingt lokale Richtlinien, bevor Sie externe Aufrufe verwenden.
  • Überprüfen Sie unbedingt die Menge des Datendurchsatzes, bevor Sie eine Abhängigkeit übernehmen. Für instance ist das Pulldown des gesamten externen Datasets möglicherweise nicht die beste Option, und stattdessen sollte die Paginierung verwendet werden, um Daten in Blöcken abzurufen.

Abrufen von Informationen mit fetch

Die Abruf-API ruft Informationen aus externen Diensten ab. Da es sich um eine async API handelt, müssen Sie die main Signatur Ihres Skripts anpassen. Legen Sie die Funktion asyncfestmain. Sie sollten auch auf den Aufruf und json abruf fetch achtenawait. Dadurch wird sichergestellt, dass diese Vorgänge abgeschlossen werden, bevor das Skript beendet wird.

Alle von abgerufenen fetch JSON-Daten müssen mit einer im Skript definierten Schnittstelle übereinstimmen. Der zurückgegebene Wert muss einem bestimmten Typ zugewiesen werden, da Office-Skripts den any Typ nicht unterstützen. Informationen zu den Namen und Typen der zurückgegebenen Eigenschaften finden Sie in der Dokumentation für Ihren Dienst. Fügen Sie ihrem Skript dann die entsprechende Schnittstelle oder Schnittstellen hinzu.

Das folgende Skript verwendet fetch zum Abrufen von JSON-Daten vom Testserver in der angegebenen URL. Beachten Sie die JSONData Schnittstelle zum Speichern der Daten als übereinstimmenden Typ.

async function main(workbook: ExcelScript.Workbook) {
  // Retrieve sample JSON data from a test server.
  let fetchResult = await fetch('https://jsonplaceholder.typicode.com/todos/1');

  // Convert the returned data to the expected JSON structure.
  let json : JSONData = await fetchResult.json();

  // Display the content in a readable format.
  console.log(JSON.stringify(json));
}

/**
 * An interface that matches the returned JSON structure.
 * The property names match exactly.
 */
interface JSONData {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

Weitere fetch Beispiele

Einschränken externer Aufrufe mit Information Rights Management (IRM)

Sie können IRM-Einstellungen auf eine Arbeitsmappe anwenden, um zu verhindern, dass externe Aufrufe von Skripts erfolgen. Deaktivieren Sie die Copy/EXTRACT-Richtlinie, um dieses Verhalten zu verhindern.

Externe Aufrufe von Power Automate

Externe API-Aufrufe schlagen fehl, wenn ein Skript über Power Automate ausgeführt wird. Ein fetch Aufruf gibt die Fehlermeldung "Runtime error: Line X: fetch is not defined" (Laufzeitfehler: Zeile X: Fetch ist nicht definiert) aus. Überprüfen Sie ihre Skripts auf solche Verweise, bevor Sie sie in einen Flow integrieren.

Sie müssen HTTP mit Azure AD oder anderen äquivalenten Aktionen verwenden, um Daten aus einem externen Dienst zu pullen oder zu pushen.

Warnung

Externe Aufrufe, die über den Power Automate Excel Online-Connector ausgeführt werden, schlagen fehl, um vorhandene Richtlinien zur Verhinderung von Datenverlust aufrechtzuerhalten. Skripts, die über Power Automate ausgeführt werden, werden jedoch außerhalb Ihrer organization und außerhalb der Firewalls Ihres organization ausgeführt. Für zusätzlichen Schutz vor böswilligen Benutzern in dieser externen Umgebung kann Ihr Administrator die Verwendung von Office-Skripts steuern. Ihr Administrator kann entweder den Excel Online-Connector in Power Automate deaktivieren oder Office-Skripts für Excel über die Office-Skripts-Administratorsteuerelemente deaktivieren.

Siehe auch