Connectormethoden für generative Seiten

Verwenden Sie die Connectormethoden des dataApi Objekts, um mit Daten zu arbeiten, die von einem An die Seite gebundenen Power Platform-Connector verfügbar gemacht werden.

Hinweis

Connectormethoden sind im freigegebenen dataApi Vertrag optional. Einige Hosts implementieren sie nicht. Überprüfen Sie daher, ob eine Methode vorhanden ist, bevor Sie sie aufrufen. Eine vorhandene Methode bedeutet nicht, dass die Seite über einen Anbinder verfügt oder dass die Verbindung, das Dataset, die Tabelle oder der Vorgang wie erwartet konfiguriert, autorisiert oder zulässig ist.

Im Gegensatz zu den Aktions- und Funktionsmethoden lehnen Connectormethoden die zurückgegebene Zusage ab, wenn ein Aufruf fehlschlägt, z. B. wenn der Verbindungsverweis nicht aufgelöst werden kann, wird die Verbindung nicht autorisiert, und der Benutzer schließt die Zustimmungsaufforderung nicht ab, oder der Connector gibt einen Fehlerstatus zurück. executeConnectorOperation löst bei ok: false den meisten Fehlerstatus auf, lehnt jedoch trotzdem für einen fehlenden Vorgang, eine nicht autorisierte Verbindung (403) ohne vollständige Zustimmung oder einen Transportfehler ab. Umschließen von Connectoranrufen in try/catch.

Methode	Description
createConnectorRow	Erstellt eine neue Zeile in der angegebenen Verbindertabelle.
deleteConnectorRow	Löscht eine Zeile aus der angegebenen Verbindertabelle.
executeConnectorOperation	Ruft einen benannten Vorgang auf, der von einem REST-Connector (Operation-Keyed) verfügbar gemacht wird, z. B. Office 365-Benutzer.
getConnectorSwagger	Ruft die Swagger-Definition (OpenAPI) für den Connector ab.
getConnectorTableSchema	Ruft das Schema für eine Tabelle (auch als Entität oder Liste bezeichnet) ab, die vom Connector verfügbar gemacht wird.
listConnectorDatasets	Listet die datasets auf, die für den Connector verfügbar sind.
listConnectorOperations	Listet die Vorgänge auf, die von einem REST-Connector (operation-keyed) verfügbar gemacht werden.
listConnectorTables	Listet die Tabellen auf, die im angegebenen Connector-Dataset verfügbar sind.
queryConnectorTable	Fragt eine Tabelle ab, die vom Connector mit den angegebenen Optionen verfügbar gemacht wird.
retrieveConnectorRow	Ruft eine einzelne Zeile aus der angegebenen Verbindertabelle ab.
updateConnectorRow	Aktualisiert eine vorhandene Zeile in der angegebenen Verbindertabelle.

queryConnectorTable Methode

Fragt eine Tabelle ab, die vom Connector mithilfe der angegebenen Optionen verfügbar gemacht wird.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist (z. B sp_shared_sharepointonline. ).
dataset	string	Das Dataset, das die Tabelle enthält, z. B. eine SharePoint Website-URL.
tableName	string	Der interne Name der Tabelle aus der name eigenschaft, die von listConnectorTables. Verwenden Sie nicht den Anzeigenamen.
options	QueryConnectorTableOptions	Optionen zum Abfragen der Tabelle.

QueryConnectorTableOptions

Name	Type	Description
select	string[]	(Empfohlen) Array von Spaltennamen, die abgerufen werden sollen.
filter	string	(Optional) Filterausdruck, der vom Connector unterstützt wird.
orderBy	string	(Optional) Order-by-Ausdruck, der vom Connector unterstützt wird.
top	number	(Optional) Maximale Anzahl von Zeilen, die zurückgegeben werden sollen.

Rücklieferungen

Eine Zusage , die das Ergebnis des Vorgangs enthält. Wenn der Vorgang erfolgreich verläuft, gibt die Zusage ein Objekt zurück, das eine Datentabelle mit den Ergebnissen mit den folgenden Eigenschaften enthält:

Name	Type	Description
rows	Object[]	Array von Zeilendaten.
hasMoreRows	boolean	Gibt an, ob weitere Zeilen verfügbar sind.

queryConnectorTable gibt eine einzelne Seite mit Ergebnissen zurück. Es gibt keine Fortsetzungsfunktion zurück, und es gibt derzeit keine unterstützte Möglichkeit, die nächste Seite abzurufen. Wenn hasMoreRows dies der Wert ist true, wurden mehr Zeilen übereinstimmen, als zurückgegeben wurden. Schränken Sie die Abfrage mit filterein, oder teilen Sie dem Benutzer mit, dass die Ergebnisse unvollständig sind.

queryConnectorTable-Beispiel

if (!dataApi.listConnectorTables || !dataApi.queryConnectorTable) {
  throw new Error("Connector methods aren't available on this page.");
}

const tables = await dataApi.listConnectorTables(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing"
);
const documentsTable = tables.find((table) => table.displayName === "Documents");
if (!documentsTable) {
  throw new Error("The Documents table wasn't found in this dataset.");
}
const documentsTableName = documentsTable.name;

const result = await dataApi.queryConnectorTable(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName,
  {
    select: ["Title", "Modified"],
    top: 50,
  }
);

In den folgenden Beispielen wird davon ausgegangen, dass documentsTableName die Tabelle wie oben dargestellt die Tabelle namelistConnectorTablesenthält.

listConnectorTables Methode

Listet die Tabellen (Listen oder Entitäten) auf, die im angegebenen Connector-Dataset verfügbar sind.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
dataset	string	Das Dataset, für das Tabellen aufgeführt werden sollen.

Rücklieferungen

Eine Zusage , die ein Array von Tabelleninformationen enthält. Jeder Eintrag hat folgende Eigenschaften:

Name	Type	Description
name	string	Der interne Name der Tabelle.
displayName	string	Der Anzeigename der Tabelle.

listConnectorTables(Beispiel)

const tables = await dataApi.listConnectorTables?.(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing"
);

listConnectorDatasets Methode

Listet die für den Connector verfügbaren Datasets auf, z. B. die SharePoint Websites, auf die eine Verbindung zugreifen kann.

Parameters

Legen Sie einen Wert für diesen erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.

Rücklieferungen

Eine Zusage , die ein Array von Datasetinformationen enthält. Jeder Eintrag hat folgende Eigenschaften:

Name	Type	Description
name	string	Der interne Name oder bezeichner des Datasets.
displayName	string	Der Anzeigename des Datasets.

listConnectorDatasets(Beispiel)

const datasets = await dataApi.listConnectorDatasets?.("sp_shared_sharepointonline");

listConnectorOperations Methode

Listet die vorgänge auf, die in der Swagger-Definition des Connectors definiert sind, mit Ausnahme von Vorgängen, die als intern gekennzeichnet sind, sortiert nach Anzeigename. Diese Methode ist für REST-Connectors (Operation-Keyed) wie Office 365-Benutzer am nützlichsten. Verwenden Sie für tabellarische Verbinder die Abfrage- und Zeilenmethoden anstelle der Vorgänge, die diese Methode auflistet.

Parameters

Legen Sie einen Wert für diesen erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.

Rücklieferungen

Eine Zusage , die ein Array von Vorgangsinformationen enthält. Jeder Eintrag hat folgende Eigenschaften:

Name	Type	Description
name	string	Die Vorgangs-ID gemäß definition der Swagger-Definition des Connectors. Übergeben Sie diesen Wert an executeConnectorOperation.
displayName	string	Der lesbare Vorgangsname für die Anzeige, z. B. die Swagger-Zusammenfassung. Fällt zurück, name wenn keine Zusammenfassung definiert ist.

listConnectorOperations-Beispiel

const operations = await dataApi.listConnectorOperations?.("sp_shared_sharepointonline");

getConnectorSwagger Methode

Ruft die Swagger-Definition (OpenAPI) für den Connector ab, die die verfügbaren Vorgänge beschreibt. Das zurückgegebene Dokument beschreibt den Verbinder insgesamt. Es enthält keine Tabellenspaltenschemas für tabellarische Verbinder. Wird für diese Informationen verwendet getConnectorTableSchema .

Parameters

Legen Sie einen Wert für diesen erforderlichen Parameter fest.

Name	Type	Description
connectorApiId	string	Der Connector-API-Bezeichner, z /providers/Microsoft.PowerApps/apis/shared_sharepointonline. B. . Dieser Bezeichner unterscheidet sich vom logischen Namen (connectorLogicalName) des Verbindungsverweises, der von den meisten anderen Connectormethoden verwendet wird.

Rücklieferungen

Eine Zusage , die die Swagger-Definition des Connectors als Objekt enthält.

getConnectorSwagger-Beispiel

if (!dataApi.getConnectorSwagger) {
  throw new Error("getConnectorSwagger isn't available on this page.");
}

const swagger = await dataApi.getConnectorSwagger(
  "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"
);

getConnectorTableSchema Methode

Ruft das Schema (Spaltendefinitionen) für eine Tabelle ab, die vom Connector verfügbar gemacht wird. Der Verbinder definiert das zurückgegebene Schema und variiert je nach Verbinder. Gehen Sie nicht davon aus, dass sie jede dynamische Spalte enthält, die eine Tabelle enthalten kann.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
dataset	string	Das Dataset, das die Tabelle enthält.
tableName	string	Der interne Name der Tabelle aus der name eigenschaft, die von listConnectorTables. Verwenden Sie nicht den Anzeigenamen.

Rücklieferungen

Eine Zusage , die das Schema der Tabelle als Objekt enthält.

getConnectorTableSchema-Beispiel

if (!dataApi.getConnectorTableSchema) {
  throw new Error("getConnectorTableSchema isn't available on this page.");
}

const schema = await dataApi.getConnectorTableSchema(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName // from listConnectorTables
);

retrieveConnectorRow Methode

Ruft eine einzelne Zeile aus der angegebenen Verbindertabelle ab.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
dataset	string	Das Dataset, das die Tabelle enthält.
tableName	string	Der interne Name der Tabelle aus der name eigenschaft, die von listConnectorTables. Verwenden Sie nicht den Anzeigenamen.
id	string	Die ID der abzurufenden Zeile.
options	RetrieveConnectorRowOptions	(Optional) Optionen zum Abrufen der Zeile.

RetrieveConnectorRowOptions

Name	Type	Description
select	string[]	(Empfohlen) Array von Spaltennamen, die abgerufen werden sollen. Wenn sie weggelassen wird, wird keine $select Projektion gesendet – der Verbinder bestimmt, welche Spalten zurückgegeben werden sollen, und garantiert nicht, dass jede Spalte in der Zeile zurückgegeben wird.

Rücklieferungen

Eine Zusage , die die Zeilendaten enthält.

retrieveConnectorRow-Beispiel

if (!dataApi.retrieveConnectorRow) {
  throw new Error("retrieveConnectorRow isn't available on this page.");
}

const row = await dataApi.retrieveConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1"
);

createConnectorRow Methode

Erstellt eine neue Zeile in der angegebenen Verbindertabelle.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
dataset	string	Das Dataset, das die Tabelle enthält.
tableName	string	Der interne Name der Tabelle aus der name eigenschaft, die von listConnectorTables. Verwenden Sie nicht den Anzeigenamen.
row	object	Die zu erstellenden Zeilendaten.

Rücklieferungen

Eine Zusage , die den Antworttext enthält, der vom Connector zurückgegeben wird, falls vorhanden. Je nach Verbinder kann dieser Wert die erstellte Zeile, eine Teilzeile oder kein Wert sein.

createConnectorRow-Beispiel

if (!dataApi.createConnectorRow) {
  throw new Error("createConnectorRow isn't available on this page.");
}

const newRow = await dataApi.createConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  { Title: "New document" }
);

updateConnectorRow Methode

Aktualisiert eine vorhandene Zeile in der angegebenen Verbindertabelle.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
dataset	string	Das Dataset, das die Tabelle enthält.
tableName	string	Der interne Name der Tabelle aus der name eigenschaft, die von listConnectorTables. Verwenden Sie nicht den Anzeigenamen.
id	string	Die ID der zu aktualisierenden Zeile.
row	object	Die zu aktualisierenden Zeilendaten.

Rücklieferungen

Eine Zusage , die den Antworttext enthält, der vom Connector zurückgegeben wird, falls vorhanden. Je nach Verbinder kann dieser Wert die aktualisierte Zeile, eine Teilzeile oder kein Wert sein. Rufen Sie auf, um retrieveConnectorRowdie aktuellen Werte der Zeile zu lesen.

updateConnectorRow-Beispiel

if (!dataApi.updateConnectorRow) {
  throw new Error("updateConnectorRow isn't available on this page.");
}

const updatedRow = await dataApi.updateConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1",
  { Title: "Updated title" }
);

deleteConnectorRow Methode

Löscht eine Zeile aus der angegebenen Verbindertabelle.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
dataset	string	Das Dataset, das die Tabelle enthält.
tableName	string	Der interne Name der Tabelle aus der name eigenschaft, die von listConnectorTables. Verwenden Sie nicht den Anzeigenamen.
id	string	Die ID der zu löschenden Zeile.

Rücklieferungen

Eine Zusage , die das Ergebnis des Vorgangs enthält. Wenn der Vorgang erfolgreich ist, wird kein Wert zurückgegeben.

deleteConnectorRow-Beispiel

if (!dataApi.deleteConnectorRow) {
  throw new Error("deleteConnectorRow isn't available on this page.");
}

await dataApi.deleteConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1"
);

executeConnectorOperation Methode

Ruft einen benannten Vorgang auf, der von einem REST-Connector (Operation-Keyed) verfügbar gemacht wird, z. B. HTTP, Teams-Sendenachricht oder Office 365-Benutzer. Tabellarische Verbinder sollten stattdessen die CRUD-Methoden für Abfrage und Zeile verwenden.

Parameters

Legen Sie Werte für diese erforderlichen Parameter fest.

Name	Type	Description
connectorLogicalName	string	Der logische Name des Verbindungsverweises, der an die Seite gebunden ist.
operationName	string	Die Vorgangs-ID gemäß definition der Swagger-Definition des Connectors.
parameters	object	Die parameter, die für den Vorgang erforderlich sind. Übergeben Sie ein leeres Objekt ({}), wenn der Vorgang keine Parameter akzeptiert . Dieser Parameter ist auch dann erforderlich, wenn nichts gesendet werden soll.

Rücklieferungen

Eine Zusage , die das Vorgangsergebnis mit diesen Eigenschaften enthält. Die Zusage lehnt ab, wenn der Verbindungsverweis nicht aufgelöst werden kann, die Swagger-Definition des Connectors nicht abgerufen werden kann, der Vorgang darin nicht gefunden wird, der Aufruf kann nicht verteilt werden, oder die Verbindung ist nicht autorisiert (HTTP 403), und der Benutzer schließt die Verbindungszustimmungsaufforderung nicht ab.

Name	Type	Description
ok	boolean	true wenn der zugrunde liegende HTTP-Status kleiner als 400 ist. Dieser Status enthält Umleitungsstatus (3xx), behandeln Sie also nicht ok allein als Nachweis für die zurückgegebenen Daten – auch überprüfen status oder prüfen body.
status	number	Der unformatierte HTTP-Statuscode, der vom Connector zurückgegeben wird.
body	unknown	Der analysierte JSON-Antworttext oder die unformatierte Zeichenfolge, wenn der Text nicht JSON ist.

executeConnectorOperation (Beispiel)

Im folgenden Beispiel wird ein Vorgang mit dem Namen CopyFilesourceUrl angenommen und destinationUrl Parameter vorausgesetzt. Überprüfen Sie die Vorgangs-ID und ihre Parameter anhand der eigenen Swagger-Definition des Connectors (z. B. mit listConnectorOperations oder getConnectorSwagger) vor der Verwendung, da verfügbare Vorgänge und ihre Parameter je nach Connector variieren.

if (!dataApi.executeConnectorOperation) {
  throw new Error("executeConnectorOperation isn't available on this page.");
}

try {
  const result = await dataApi.executeConnectorOperation(
    "sp_shared_sharepointonline",
    "CopyFile",
    { sourceUrl: "/sites/Marketing/Shared Documents/file.docx", destinationUrl: "/sites/Sales/Shared Documents/file.docx" }
  );

  if (result.ok) {
    console.log(result.body);
  }
  else {
    console.log(result.status);
  }
}
catch (error) {
  console.log(error);
}