Intégration IFS Cloud

IFS Cloud connection configuration.

IFS Cloud OData client.

High-level IFS read helpers for Spark and Lakehouse.

Fabric Key Vault helpers for IFS credentials.

IFS API error types.

IFS Cloud integration for Microsoft Fabric.

class fabrictools.integrations.ifs.IFSClient(config: IFSConfig, *, check_connectivity: bool = True)

Bases: object

Read-only client for IFS Cloud OData entity sets.

property config: IFSConfig

get_access_token(*, force_refresh: bool = False) → str[source]: Return a valid OAuth2 access token.

get_entity(projection: str, entity_set: str, *, odata_filter: str | None = None, select: list[str] | None = None, top: int | None = None, skip: int | None = None, orderby: str | None = None, fetch_all: bool = False) → list[dict[str, Any]][source]

Read rows from an IFS OData entity set.

When fetch_all is True, all pages are retrieved using @odata.nextLink when available, otherwise $skip pagination with config.page_size.

class fabrictools.integrations.ifs.IFSConfig(host: str, client_id: str, client_secret: str, layer: str = 'int', token_endpoint: str | None = None, scope: str = 'openid microprofile-jwt', projection_version: str = 'v1', timeout_seconds: int = 60, page_size: int = 1000)

Bases: object

Connection settings for IFS Cloud OData APIs.

Parameters:

host – IFS host URL (e.g. https://ifs.example.com).
client_id – IAM client identifier.
client_secret – IAM client secret.
layer – API exposure layer — main, int, or b2b.
token_endpoint – OAuth2 token URL. When omitted, derived from host.
scope – OAuth2 scope (IFS examples use openid microprofile-jwt).
projection_version – OData projection API version segment (default v1).
timeout_seconds – HTTP request timeout in seconds.
page_size – Default $top page size when fetch_all is enabled.

client_id: str

client_secret: str

host: str

layer: str = 'int'

page_size: int = 1000

projection_base_path() → str[source]: Return the OData projection base path segment.

projection_version: str = 'v1'

resolve_token_endpoint() → str[source]: Return the OAuth2 token endpoint URL.

scope: str = 'openid microprofile-jwt'

timeout_seconds: int = 60

token_endpoint: str | None = None

exception fabrictools.integrations.ifs.IFSError(message: str, *, status_code: int | None = None, error_code: str | None = None, details: list[dict[str, Any]] | None = None, response_body: str | None = None)

Bases: Exception

Raised when an IFS HTTP or OData request fails.

classmethod from_http_response(status_code: int, body: str) → IFSError[source]: Build an IFSError from an HTTP status and response body.

fabrictools.integrations.ifs.diagnose_ifs_connectivity(config: IFSConfig) → dict[str, Any]

Vérifie la résolution DNS des hôtes IFS avant un appel API.

Utile dans Fabric pour détecter tôt les hostnames internes (.lcl, .local, etc.) non joignables depuis le cluster cloud.

Returns:: Dictionnaire avec les checks host et token_endpoint.

fabrictools.integrations.ifs.ifs_config_with_keyvault_secret(*, host: str, client_id: str, keyvault_url: str, client_secret_name: str, **kwargs: Any) → IFSConfig

Build an IFSConfig using a client secret stored in Fabric Key Vault.

Parameters:

host – IFS host URL.
client_id – IAM client identifier.
keyvault_url – Azure Key Vault URL linked to the Fabric workspace.
client_secret_name – Secret name holding the IAM client secret.
kwargs – Additional IFSConfig fields (layer, token_endpoint, etc.).

fabrictools.integrations.ifs.ifs_data_to_dataframe(ifs_data: str, *, spark: pyspark.sql.SparkSession | None = None) → pyspark.sql.DataFrame

Build a Spark DataFrame from an IFS JSON string.

Handles columns that are entirely null, which Spark cannot infer on its own.

Parameters:

ifs_data – JSON string — array of entities or OData {"value": [...]}.
spark – Optional Spark session; active session is used when omitted.

fabrictools.integrations.ifs.ifs_request_json(access_token: str, url: str, *, method: str = 'GET', timeout_seconds: int = 60, data: bytes | None = None) → dict[str, Any]

Execute an authenticated IFS API request and parse the JSON response.

Parameters:

access_token – OAuth2 bearer token already obtained.
url – Full request URL.
method – HTTP method (default GET).
timeout_seconds – Request timeout in seconds.
data – Optional request body.

fabrictools.integrations.ifs.parse_ifs_data(ifs_data: str) → list[dict[str, Any]]

Parse an IFS JSON string into a list of entity rows.

Accepts either a JSON array of entities or an OData collection object with a value array (as returned by IFS OData endpoints).

Parameters:: ifs_data – JSON string (e.g. Fabric pipeline activity output).
Raises:: IFSError – When the string is not valid JSON or has an unsupported shape.

fabrictools.integrations.ifs.read_ifs_entity(config: IFSConfig, projection: str, entity_set: str, *, odata_filter: str | None = None, select: list[str] | None = None, fetch_all: bool = True, spark: pyspark.sql.SparkSession | None = None) → pyspark.sql.DataFrame

Read an IFS OData entity set and return a Spark DataFrame.

Parameters:

config – IFS connection settings.
projection – OData projection service name (e.g. ActivityService).
entity_set – Entity set name (e.g. Activities).
odata_filter – Optional OData $filter expression.
select – Optional list of fields for $select.
fetch_all – When True, paginate through all result pages.
spark – Optional Spark session; active session is used when omitted.

fabrictools.integrations.ifs.read_ifs_entity_with_token(access_token: str, host: str, projection: str, entity_set: str, *, layer: str = 'int', odata_filter: str | None = None, select: list[str] | None = None, top: int | None = None, skip: int | None = None, orderby: str | None = None, fetch_all: bool = False, projection_version: str = 'v1', page_size: int = 1000, timeout_seconds: int = 60) → list[dict[str, Any]]

Read an IFS OData entity set using a pre-generated access token.

Parameters:

access_token – OAuth2 bearer token string.
host – IFS host URL (e.g. https://ifs.example.com).
projection – OData projection service name (e.g. CustomerHandling).
entity_set – Entity set name (e.g. CustomerInfoSet).
layer – API exposure layer — main, int, or b2b.
odata_filter – Optional OData $filter expression.
select – Optional list of fields for $select.
top – Optional $top page size for a single request.
skip – Optional $skip offset.
orderby – Optional $orderby expression.
fetch_all – When True, paginate through all result pages.
projection_version – OData projection API version segment.
page_size – Default $top when fetch_all is enabled.
timeout_seconds – HTTP request timeout in seconds.

fabrictools.integrations.ifs.read_ifs_to_lakehouse(config: IFSConfig, projection: str, entity_set: str, lakehouse_name: str, relative_path: str, *, odata_filter: str | None = None, select: list[str] | None = None, mode: str = 'overwrite', fetch_all: bool = True, spark: pyspark.sql.SparkSession | None = None) → pyspark.sql.DataFrame

Read an IFS entity set and write the result to a Fabric Lakehouse.

Parameters:

config – IFS connection settings.
projection – OData projection service name.
entity_set – Entity set name.
lakehouse_name – Target Lakehouse display name.
relative_path – Lakehouse relative path (e.g. Tables/dbo/ifs_activities).
odata_filter – Optional OData $filter expression.
select – Optional list of fields for $select.
mode – Lakehouse write mode (default overwrite).
fetch_all – When True, paginate through all result pages.
spark – Optional Spark session.

fabrictools.integrations.ifs.write_ifs_data_to_lakehouse(ifs_data: str, lakehouse_name: str, relative_path: str, *, mode: str = 'overwrite', partition_by: list[str] | None = None, format: str = 'delta', spark: pyspark.sql.SparkSession | None = None, merge_condition: str | None = None, upsert_key_columns: Sequence[str] | None = None, normalize_column_names: bool = True, enable_column_mapping: bool = False, auto_partition: bool = False, auto_partition_threshold_bytes: int = 1073741824) → pyspark.sql.DataFrame

Convert an IFS JSON string to a Spark DataFrame and write it to a Lakehouse.

Parameters:

ifs_data – JSON string — array of entities or OData {"value": [...]}.
lakehouse_name – Target Lakehouse display name.
relative_path – Lakehouse relative path (e.g. Tables/dbo/ifs_customers).
mode – Lakehouse write mode (default overwrite).
partition_by – Optional partition columns for the write.
format – Output format (default delta).
spark – Optional Spark session; active session is used when omitted.

fabrictools.integrations.ifs.write_ifs_data_to_lakehouses(requests: list[dict[str, Any]], *, max_workers: int | None = None, continue_on_error: bool = False, spark: pyspark.sql.SparkSession | None = None) → dict[str, Any]

Convert multiple IFS JSON strings to DataFrames and write them in parallel.

Each request must contain ifs_data, lakehouse_name and relative_path. Optional keys mirror write_lakehouse(): mode, partition_by, format, merge_condition, upsert_key_columns, name, normalize_column_names, enable_column_mapping, auto_partition and auto_partition_threshold_bytes.

DataFrame conversion runs sequentially on the driver; Lakehouse writes run in parallel via write_lakehouses().