Files

573 lines
26 KiB
JSON

{
"swagger": "2.0",
"info": {
"title": "Cosmos DB Database REST APIs",
"version": "v1"
},
"schemes": [
"https"
],
"host": "api.fabric.microsoft.com",
"basePath": "/v1",
"paths": {
"/workspaces/{workspaceId}/cosmosDbDatabases": {
"get": {
"summary": "Returns a list of Cosmos DB databases from the specified workspace.",
"description": "## Permissions\n\n The caller must have a *viewer* workspace role. \n\n## Required Delegated Scopes\n\nWorkspace.Read.All or Workspace.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_ListCosmosDBDatabases",
"x-ms-pageable": {
"nextLinkName": "continuationUri"
},
"produces": [
"application/json"
],
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "query",
"name": "recursive",
"description": "Lists items in a folder and its nested folders, or just a folder only. True - All items in the folder and its nested folders are listed, False - Only items in the folder are listed. The default value is true.",
"type": "boolean",
"required": false
},
{
"in": "query",
"name": "rootFolderId",
"description": "This parameter allows users to filter items based on a specific root folder. If not provided, the workspace is used as the root folder.",
"type": "string",
"format": "uuid",
"required": false
},
{
"in": "query",
"name": "continuationToken",
"description": "A token for retrieving the next page of results.",
"type": "string",
"required": false
}
],
"responses": {
"200": {
"description": "Request completed successfully.",
"schema": {
"$ref": "./definitions.json#/definitions/CosmosDBDatabases"
}
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* InvalidItemType - Invalid item type.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"List Cosmos DB Databases in workspace example": {
"$ref": "./examples/ListCosmosDBDatabasesInWorkspace.json"
}
}
},
"post": {
"summary": "Creates a Cosmos DB database in the specified workspace.",
"description": "This API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\n ## Permissions \n The caller must have a *contributor* workspace role. \n\n## Required Delegated Scopes\n\n Item.ReadWrite.All \n\n## Limitations \n- To create a Cosmos DB database the workspace must be on a supported Fabric capacity. For more information see: [Microsoft Fabric license types](/fabric/enterprise/licenses#microsoft-fabric-license-types).\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_CreateCosmosDBDatabase",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"x-ms-fabric-sdk-long-running-operation": true,
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "body",
"name": "createCosmosDBDatabaseRequest",
"description": "Create item request payload.",
"schema": {
"$ref": "./definitions.json#/definitions/CreateCosmosDBDatabaseRequest"
},
"required": true
}
],
"responses": {
"201": {
"description": "Successfully created",
"schema": {
"$ref": "./definitions.json#/definitions/CosmosDBDatabase"
}
},
"202": {
"description": "Request accepted, Cosmos DB database provisioning in progress.",
"headers": {
"Location": {
"description": "The URL of the operation status, which can be used to track the operation state.",
"type": "string"
},
"x-ms-operation-id": {
"description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.",
"type": "string",
"format": "uuid"
},
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
}
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* InvalidItemType - Item type is invalid\n\n* ItemDisplayNameAlreadyInUse - Item display name is already used.\n\n* CorruptedPayload - The provided payload is corrupted.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Create a Cosmos DB Database example": {
"$ref": "./examples/CreateCosmosDBDatabase.json"
},
"Create a Cosmos DB Database with definition example": {
"$ref": "./examples/CreateCosmosDBDatabaseWithDefinition.json"
}
}
}
},
"/workspaces/{workspaceId}/cosmosDbDatabases/{cosmosDbDatabaseId}": {
"get": {
"summary": "Returns properties of the specified Cosmos DB database.",
"description": "## Permissions\n\n The caller must have *read* permissions for the Cosmos DB database. \n\n## Required Delegated Scopes\n\n Item.Read.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_GetCosmosDBDatabase",
"produces": [
"application/json"
],
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "path",
"name": "cosmosDbDatabaseId",
"description": "The Cosmos DB database ID.",
"type": "string",
"format": "uuid",
"required": true
}
],
"responses": {
"200": {
"description": "Request completed successfully.",
"schema": {
"$ref": "./definitions.json#/definitions/CosmosDBDatabase"
}
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* ItemNotFound - The requested item was not found.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Get a Cosmos DB Database example": {
"$ref": "./examples/GetCosmosDBDatabase.json"
}
}
},
"patch": {
"summary": "Updates the properties of the specified Cosmos DB database.",
"description": "## Permissions\n\n The caller must have *read and write* permissions for the Cosmos DB database.\n\n## Required Delegated Scopes\n\n Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_UpdateCosmosDBDatabase",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "path",
"name": "cosmosDbDatabaseId",
"description": "The Cosmos DB database ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "body",
"name": "updateCosmosDBDatabaseRequest",
"description": "Update Cosmos DB database request payload.",
"schema": {
"$ref": "./definitions.json#/definitions/UpdateCosmosDBDatabaseRequest"
},
"required": true
}
],
"responses": {
"200": {
"description": "Request completed successfully.",
"schema": {
"$ref": "./definitions.json#/definitions/CosmosDBDatabase"
}
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* ItemNotFound - The requested item was not found. \n\n* InvalidRequest - Invalid update request.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Update a Cosmos DB Database example": {
"$ref": "./examples/UpdateCosmosDBDatabase.json"
}
}
},
"delete": {
"summary": "Deletes the specified Cosmos DB database.",
"description": "## Permissions\n\n The caller must have *write* permissions for the Cosmos DB database.\n\n## Required Delegated Scopes\n\n Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_DeleteCosmosDBDatabase",
"produces": [
"application/json"
],
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "path",
"name": "cosmosDbDatabaseId",
"description": "The Cosmos DB database ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "query",
"name": "hardDelete",
"description": "Specifies whether to perform a hard delete. When set to `true`, the item is permanently deleted and cannot be recovered. When set to `false` or not specified, the item is soft-deleted if the item type supports it.",
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Request completed successfully."
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* ItemNotFound - The requested item was not found.\n\n* InsufficientWorkspaceRole - User doesn't have sufficient workspace role.\n\n* FeatureNotAvailable - This could be due to the soft deletion feature not being available.\n\n* UnsupportedItemType - This could be due to the soft deletion feature not supported by the requested item type.\n\n* TenantSwitchDisabled - This could be due to the soft deletion feature being disabled by the tenant admin.\n\n* InvalidTargetItemStateForSoftDeletion - The item is in invalid states for soft deletion.\n\n* InvalidParentItemStateForSoftDeletion - The item's parent item is not in Active state.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Delete a Cosmos DB Database example": {
"$ref": "./examples/DeleteCosmosDBDatabase.json"
},
"Hard delete a Cosmos DB database example": {
"$ref": "./examples/HardDeleteCosmosDBDatabase.json"
}
}
}
},
"/workspaces/{workspaceId}/cosmosDbDatabases/{cosmosDbDatabaseId}/getDefinition": {
"post": {
"summary": "Returns the specified Cosmos DB database public definition.",
"description": "This API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\nWhen you get a Cosmos DB database's public definition, the sensitivity label is not a part of the definition.\n\n## Permissions\n\n The caller must have *read and write* permissions for the CosmosDBDatabase. \n\n## Required Delegated Scopes \n\n Item.ReadWrite.All \n\n## Limitations\n\nTo retrieve the definition of a Cosmos DB database item protected by an encrypted sensitivity label, the caller must have sufficient [usage rights](/fabric/enterprise/powerbi/service-security-sensitivity-label-change-enforcement) to remove the label, as configured in [Microsoft Purview](/purview/purview).\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_GetCosmosDBDatabaseDefinition",
"produces": [
"application/json"
],
"x-ms-fabric-sdk-long-running-operation": true,
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "path",
"name": "cosmosDbDatabaseId",
"description": "The Cosmos DB database ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "query",
"name": "format",
"description": "The format of the Cosmos DB database public definition.",
"type": "string",
"required": false
}
],
"responses": {
"200": {
"description": "Request completed successfully.",
"schema": {
"$ref": "./definitions.json#/definitions/CosmosDBDatabaseDefinitionResponse"
}
},
"202": {
"description": "Request accepted. Retrieving the definition is in progress.",
"headers": {
"Location": {
"description": "The URL of the operation status, which can be used to track the operation state.",
"type": "string"
},
"x-ms-operation-id": {
"description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.",
"type": "string",
"format": "uuid"
},
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
}
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* OperationNotSupportedForItem - Operation not supported for requested item.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Get a Cosmos DB Database public definition example": {
"$ref": "./examples/GetCosmosDBDatabaseDefinition.json"
}
}
}
},
"/workspaces/{workspaceId}/cosmosDbDatabases/{cosmosDbDatabaseId}/updateDefinition": {
"post": {
"summary": "Overrides the definition for the specified Cosmos DB database.",
"description": "This API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\n \nUpdating the Cosmos DB database's definition, does not affect its sensitivity label. \n\n## Permissions\n\n The caller must have *read and write* permissions for the CosmosDBDatabase. \n## Required Delegated Scopes \n\n Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface",
"tags": [
"Items"
],
"operationId": "Items_UpdateCosmosDBDatabaseDefinition",
"produces": [
"application/json"
],
"x-ms-fabric-sdk-long-running-operation": true,
"parameters": [
{
"in": "path",
"name": "workspaceId",
"description": "The workspace ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "path",
"name": "cosmosDbDatabaseId",
"description": "The Cosmos DB database ID.",
"type": "string",
"format": "uuid",
"required": true
},
{
"in": "query",
"name": "updateMetadata",
"description": "When set to true and the .platform file is provided as part of the definition, the item's metadata is updated using the metadata in the .platform file. \n> NOTE: \nThe CosmosDBDatabase item type does not support renaming via the .platform file.",
"type": "boolean",
"required": false
},
{
"in": "body",
"name": "updateCosmosDBDatabaseDefinitionRequest",
"description": "Update Cosmos DB database request payload.",
"schema": {
"$ref": "./definitions.json#/definitions/UpdateCosmosDBDatabaseDefinitionRequest"
},
"required": true
}
],
"responses": {
"200": {
"description": "Request completed successfully."
},
"202": {
"description": "Request accepted. Update definition is in progress.",
"headers": {
"Location": {
"description": "The URL of the operation status, which can be used to track the operation state.",
"type": "string"
},
"x-ms-operation-id": {
"description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.",
"type": "string",
"format": "uuid"
},
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
}
},
"429": {
"description": "The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.",
"x-ms-error-response": true,
"headers": {
"Retry-After": {
"type": "integer",
"description": "The number of seconds to wait before retrying the request."
}
},
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
},
"default": {
"description": "Common error codes:\n\n* OperationNotSupportedForItem - Operation not supported for requested item. \n\n* CorruptedPayload - The provided payload is corrupted.",
"schema": {
"$ref": "../common/definitions.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Update a Cosmos DB Database public definition example": {
"$ref": "./examples/UpdateCosmosDBDatabaseDefinition.json"
}
}
}
}
},
"responses": {},
"security": [],
"tags": []
}