Méthodes de connecteur pour les pages génératives

Utilisez les méthodes de connecteur de l’objet dataApi pour utiliser les données exposées par un connecteur Power Platform lié à la page.

Remarque

Les méthodes de connecteur sont facultatives dans le contrat partagé dataApi . Certains hôtes ne les implémentent pas. Vérifiez donc qu’une méthode existe avant de l’appeler. Une méthode présente ne signifie pas que la page a un connecteur qui lui est lié, ou que la connexion, le jeu de données, la table ou l’opération est configuré, autorisé ou autorisé comme prévu.

Contrairement aux méthodes d’action et de fonction, les méthodes de connecteur rejettent la promesse retournée en cas d’échec d’un appel, par exemple lorsque la référence de connexion ne peut pas être résolue, la connexion n’est pas autorisée et l’utilisateur ne termine pas l’invite de consentement, ou le connecteur retourne un état d’erreur. executeConnectorOperation résout avec ok: false la plupart des états d’erreur, mais rejette toujours pour une opération manquante, une connexion non autorisée (403) sans consentement terminé ou un échec de transport. Encapsuler les appels de connecteur dans try/catch.

Méthode	Description
createConnectorRow	Crée une ligne dans la table de connecteurs spécifiée.
deleteConnectorRow	Supprime une ligne de la table de connecteur spécifiée.
executeConnectorOperation	Appelle une opération nommée exposée par un connecteur REST (clé d’opération), telle que Utilisateurs d’Office 365.
getConnectorSwagger	Récupère la définition Swagger (OpenAPI) du connecteur.
getConnectorTableSchema	Récupère le schéma d’une table (également appelée entité ou liste) exposée par le connecteur.
listConnectorDatasets	Répertorie les jeux de données disponibles pour le connecteur.
listConnectorOperations	Répertorie les opérations exposées par un connecteur REST (clé d’opération).
listConnectorTables	Répertorie les tables disponibles dans le jeu de données du connecteur spécifié.
queryConnectorTable	Interroge une table exposée par le connecteur avec les options spécifiées.
retrieveConnectorRow	Récupère une seule ligne à partir de la table de connecteur spécifiée.
updateConnectorRow	Met à jour une ligne existante dans la table de connecteur spécifiée.

méthode queryConnectorTable

Interroge une table exposée par le connecteur à l’aide des options spécifiées.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion lié à la page (par exemple, sp_shared_sharepointonline).
dataset	string	Jeu de données qui contient la table, tel qu’une URL de site SharePoint.
tableName	string	Nom interne de la table, de la name propriété retournée par listConnectorTables. N’utilisez pas le nom complet.
options	QueryConnectorTableOptions	Options d’interrogation de la table.

QueryConnectorTableOptions

Name	Catégorie	Description
select	string[]	(Recommandé) Tableau de noms de colonnes à récupérer.
filter	string	(Facultatif) Expression de filtre prise en charge par le connecteur.
orderBy	string	(Facultatif) Expression order-by prise en charge par le connecteur.
top	number	(Facultatif) Nombre maximal de lignes à retourner.

Returns

Promesse contenant le résultat de l’opération. Une fois l’opération réussie, la promesse retourne un objet contenant une table de données avec les résultats avec les propriétés suivantes :

Name	Catégorie	Description
rows	Object[]	Tableau de données de ligne.
hasMoreRows	boolean	Indique s’il y a plus de lignes disponibles.

queryConnectorTable retourne une seule page de résultats. Elle ne retourne pas de fonction de continuation, et il n’existe actuellement aucun moyen pris en charge d’extraire la page suivante. Quand hasMoreRows c’est truele cas, plus de lignes correspondent qu’elles n’ont été retournées. Limitez la requête avec filter, ou indiquez à l’utilisateur que les résultats sont incomplets.

exemple queryConnectorTable

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,
  }
);

Les exemples suivants supposent que documentsTableName le tableau name provient listConnectorTables, comme indiqué ci-dessus.

méthode listConnectorTables

Répertorie les tables (listes ou entités) disponibles dans le jeu de données du connecteur spécifié.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
dataset	string	Jeu de données pour lequel répertorier les tables.

Returns

Promesse contenant un tableau d’informations de table. Chaque entrée a les propriétés suivantes :

Name	Catégorie	Description
name	string	Nom interne de la table.
displayName	string	Nom complet de la table.

exemple listConnectorTables

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

méthode listConnectorDatasets

Répertorie les jeux de données disponibles pour le connecteur, tels que les sites SharePoint auxquels une connexion peut accéder.

Parameters

Définissez une valeur pour ce paramètre obligatoire.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.

Returns

Promesse contenant un tableau d’informations de jeu de données. Chaque entrée a les propriétés suivantes :

Name	Catégorie	Description
name	string	Nom interne ou identificateur du jeu de données.
displayName	string	Nom complet du jeu de données.

exemple listConnectorDatasets

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

méthode listConnectorOperations

Répertorie les opérations définies dans la définition Swagger du connecteur, à l’exception des opérations marquées internes, triées par nom d’affichage. Cette méthode est plus utile pour les connecteurs REST (clé d’opération) tels que Utilisateurs d’Office 365. Pour les connecteurs tabulaires, utilisez les méthodes de requête et de ligne au lieu des opérations que cette méthode répertorie.

Parameters

Définissez une valeur pour ce paramètre obligatoire.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.

Returns

Promesse contenant un tableau d’informations d’opération. Chaque entrée a les propriétés suivantes :

Name	Catégorie	Description
name	string	ID d’opération tel que défini dans la définition Swagger du connecteur. Passez cette valeur à executeConnectorOperation.
displayName	string	Nom de l’opération lisible par l’homme pour l’affichage, tel que le résumé Swagger. Revient à name si aucun résumé n’est défini.

exemple listConnectorOperations

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

méthode getConnectorSwagger

Récupère la définition Swagger (OpenAPI) du connecteur, qui décrit les opérations qu’il expose. Le document retourné décrit le connecteur dans l’ensemble. Il n’inclut pas de schémas de colonnes par table pour les connecteurs tabulaires. Utilisez getConnectorTableSchema cette information.

Parameters

Définissez une valeur pour ce paramètre obligatoire.

Name	Catégorie	Description
connectorApiId	string	Identificateur de l’API du connecteur, tel que /providers/Microsoft.PowerApps/apis/shared_sharepointonline. Cet identificateur est différent du nom logique de référence de connexion (connectorLogicalName) utilisé par la plupart des autres méthodes de connecteur.

Returns

Promesse contenant la définition Swagger du connecteur en tant qu’objet.

exemple getConnectorSwagger

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

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

méthode getConnectorTableSchema

Récupère le schéma (définitions de colonnes) d’une table exposée par le connecteur. Le connecteur définit le schéma qu’il retourne et varie selon le connecteur. Ne supposez pas qu’elle inclut chaque colonne dynamique qu’une table peut contenir.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
dataset	string	Jeu de données qui contient la table.
tableName	string	Nom interne de la table, de la name propriété retournée par listConnectorTables. N’utilisez pas le nom complet.

Returns

Promesse contenant le schéma de la table en tant qu’objet.

exemple getConnectorTableSchema

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
);

méthode retrieveConnectorRow

Récupère une seule ligne à partir de la table de connecteur spécifiée.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
dataset	string	Jeu de données qui contient la table.
tableName	string	Nom interne de la table, de la name propriété retournée par listConnectorTables. N’utilisez pas le nom complet.
id	string	ID de la ligne à récupérer.
options	RetrieveConnectorRowOptions	(Facultatif) Options de récupération de la ligne.

RetrieveConnectorRowOptions

Name	Catégorie	Description
select	string[]	(Recommandé) Tableau de noms de colonnes à récupérer. Si elle n’est pas omise, aucune projection n’est $select envoyée : le connecteur détermine les colonnes à retourner et ne garantit pas de retourner chaque colonne de la ligne.

Returns

Promesse contenant les données de ligne.

exemple retrieveConnectorRow

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"
);

méthode createConnectorRow

Crée une ligne dans la table de connecteurs spécifiée.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
dataset	string	Jeu de données qui contient la table.
tableName	string	Nom interne de la table, de la name propriété retournée par listConnectorTables. N’utilisez pas le nom complet.
row	object	Données de ligne à créer.

Returns

Promesse contenant le corps de la réponse retourné par le connecteur, le cas échéant. Selon le connecteur, cette valeur peut être la ligne créée, une ligne partielle ou aucune valeur.

exemple createConnectorRow

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" }
);

méthode updateConnectorRow

Met à jour une ligne existante dans la table de connecteur spécifiée.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
dataset	string	Jeu de données qui contient la table.
tableName	string	Nom interne de la table, de la name propriété retournée par listConnectorTables. N’utilisez pas le nom complet.
id	string	ID de la ligne à mettre à jour.
row	object	Données de ligne à mettre à jour.

Returns

Promesse contenant le corps de la réponse retourné par le connecteur, le cas échéant. Selon le connecteur, cette valeur peut être la ligne mise à jour, une ligne partielle ou aucune valeur. Pour lire les valeurs actuelles de la ligne, appelez retrieveConnectorRow.

exemple updateConnectorRow

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" }
);

méthode deleteConnectorRow

Supprime une ligne de la table de connecteur spécifiée.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
dataset	string	Jeu de données qui contient la table.
tableName	string	Nom interne de la table, de la name propriété retournée par listConnectorTables. N’utilisez pas le nom complet.
id	string	ID de la ligne à supprimer.

Returns

Promesse contenant le résultat de l’opération. Lorsque l’opération réussit, elle ne retourne aucune valeur.

exemple deleteConnectorRow

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"
);

méthode executeConnectorOperation

Appelle une opération nommée exposée par un connecteur REST (clé d’opération), tel que HTTP, Teams send-message ou Utilisateurs d’Office 365. Les connecteurs tabulaires doivent utiliser les méthodes CRUD de requête et de ligne à la place.

Parameters

Définissez des valeurs pour ces paramètres requis.

Name	Catégorie	Description
connectorLogicalName	string	Nom logique de la référence de connexion liée à la page.
operationName	string	ID d’opération tel que défini dans la définition Swagger du connecteur.
parameters	object	Paramètres requis par l’opération. Transmettez un objet vide ({}) si l’opération n’accepte aucun paramètre , ce paramètre est requis même s’il n’y a rien à envoyer.

Returns

Promesse contenant le résultat de l’opération avec ces propriétés. La promesse rejette si la référence de connexion ne peut pas être résolue, la définition Swagger du connecteur ne peut pas être récupérée, l’opération n’est pas trouvée dans celle-ci, l’appel ne peut pas être distribué ou la connexion n’est pas autorisée (HTTP 403) et l’utilisateur ne termine pas l’invite de consentement de connexion.

Name	Catégorie	Description
ok	boolean	true lorsque l’état HTTP sous-jacent est inférieur à 400. Cet état inclut les états de redirection (3xx), donc ne traitez ok pas seul comme la preuve que l’opération a retourné les données , vérifiez ou inspectez statusbodyégalement .
status	number	Code d’état HTTP brut retourné par le connecteur.
body	unknown	Corps de la réponse JSON analysé ou chaîne brute si le corps n’est pas JSON.

exemple executeConnectorOperation

L’exemple suivant suppose une opération nommée CopyFile qui accepte et destinationUrl paramètressourceUrl. Vérifiez l’ID d’opération et ses paramètres par rapport à la définition Swagger du connecteur (par exemple, avec listConnectorOperations ou getConnectorSwagger) avant de l’utiliser, car les opérations disponibles et leurs paramètres varient selon le connecteur.

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);
}