Condividi tramite

Configurare il Data API Builder per Azure Cosmos DB per NoSQL

Azure Cosmos DB per NoSQL è un database di documenti indipendente dallo schema. A differenza dei database relazionali, Azure Cosmos DB non ha uno schema predefinito che il Data API builder (DAB) può esaminare automaticamente. Questa guida illustra come creare un file di schema GraphQL e configurare DAB per l'uso con i contenitori Azure Cosmos DB.

Prerequisiti

Comprendere il requisito dello schema

Poiché Azure Cosmos DB per NoSQL non applica uno schema, DAB non può generare automaticamente i tipi GraphQL dai dati. È invece necessario fornire un file di schema GraphQL che definisce:

  • Tipi di oggetto che rappresentano la struttura del documento del contenitore
  • Direttiva @model che esegue il mapping dei tipi GraphQL ai nomi di entità nella configurazione DAB
  • Direttiva @authorize (facoltativa) che limita l'accesso a livello di campo a ruoli specifici

È possibile creare manualmente lo schema usando gli esempi seguenti o generarlo da dati cosmos DB esistenti con il dab export comando .

Creare un file di schema GraphQL

Creare un .gql file che descrive il modello di dati. Il file di schema usa il linguaggio SDL (GraphQL Schema Definition Language) standard con direttive personalizzate per DAB.

Esempio di schema di base

Questo esempio definisce un Book tipo con campi comuni trovati in un contenitore di libri:

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
  pages: Int
  Authors: [Author]
}

type Author @model(name: "Author") {
  id: ID
  firstName: String
  lastName: String
}

Generare uno schema dai dati di Cosmos DB

Se i dati sono già presenti nei contenitori, è possibile campionarli per creare uno schema iniziale. Questo comando scrive un file di schema GraphQL dedotto nella directory di output specificata con -o.

dab export \
  --graphql \
  --generate \
  -o ./schema-out

Per impostazione predefinita, il campionamento usa TopNExtractor.

Le modalità di campionamento supportate sono TopNExtractor, EligibleDataSamplere TimePartitionedSampler.

Annotazioni

Il -o/--output parametro è obbligatorio. Se non si specifica un nome file di schema, DAB genera schema.gql nella directory di output.

Per altre modalità e opzioni, consultare la guida della CLI per dab export.

La @model direttiva è obbligatoria. Mappa il tipo GraphQL a un nome di entità nel file di configurazione DAB. Il name parametro deve corrispondere esattamente al nome dell'entità.

Annotazioni

Il Authors: [Author] campo rappresenta una matrice incorporata all'interno del documento Book, non una relazione con un contenitore separato. In Azure Cosmos DB per NoSQL i dati correlati devono essere incorporati nello stesso documento anziché archiviati in contenitori separati.

Schema con autorizzazione

Per limitare l'accesso a campi specifici, usare la @authorize direttiva . Questa direttiva accetta un roles parametro che specifica quali ruoli possono accedere al campo.

type Book @model(name: "Book") {
  id: ID
  title: String @authorize(roles: ["authenticated", "metadataviewer"])
  internalNotes: String @authorize(roles: ["editor"])
  Authors: [Author]
}

In questo esempio:

  • Il title campo è accessibile solo agli utenti con il authenticated ruolo o metadataviewer
  • Il internalNotes campo è accessibile solo agli utenti con il editor ruolo
  • I campi senza @authorize sono accessibili in base alle autorizzazioni a livello di entità

È anche possibile applicare @authorize a livello di tipo per limitare l'accesso all'intero tipo:

type InternalReport @model(name: "InternalReport") @authorize(roles: ["editor", "auditor"]) {
  id: ID
  title: String
  confidentialData: String
}

Importante

La @authorize direttiva funziona oltre alle autorizzazioni a livello di entità definite nella configurazione di runtime. Sia la direttiva che le @authorize autorizzazioni dell'entità devono consentire l'accesso per la riuscita di una richiesta.

Ad esempio, se un campo ha @authorize(roles: ["editor"]), ma l'entità non dispone di alcuna voce di autorizzazione per il ruolo editor, l'accesso a tale campo viene negato.

Avviso

@authorize(policy: "...") non è supportato in questo flusso di schema. Utilizzare il @authorize(roles: [...]).

Configurare il runtime DAB

Dopo aver creato il file di schema, configurare DAB per usarlo con l'account Azure Cosmos DB.

Inizializzare la configurazione

Usare il comando dab init per creare un file di configurazione per Azure Cosmos DB:

dab init \
  --database-type cosmosdb_nosql \
  --cosmosdb_nosql-database <your-database-name> \
  --graphql-schema schema.gql \
  --connection-string "<your-connection-string>"

Sostituire <your-database-name> con il nome del database Azure Cosmos DB e <your-connection-string> con la stringa di connessione.

Facoltativamente, includere --cosmosdb_nosql-container <your-container-name> per impostare un contenitore predefinito nella configurazione dell'origine dati.

Suggerimento

Per gli ambienti di produzione, si utilizzino le variabili di ambiente per le stringhe di connessione anziché la codifica rigida.

dab init \
    --database-type cosmosdb_nosql \
    --cosmosdb_nosql-database <your-database-name> \
    --graphql-schema schema.gql \
    --connection-string "@env('COSMOSDB_CONNECTION_STRING')"

Aggiungi entità

Aggiungere entità che corrispondono ai contenitori. Il nome dell'entità deve corrispondere al @model(name: "...") valore nello schema:

dab add Book \
  --source Book \
  --permissions "anonymous:read"

Il --source parametro accetta <container-name> o <database-name>.<container-name>. Usare il formato in due parti quando si desidera essere espliciti su database e contenitore.

File di configurazione di esempio

Dopo l'inizializzazione, il file di configurazione dovrebbe essere simile all'esempio seguente:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.2.11/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "Library",
      "schema": "schema.gql"
    },
    "connection-string": "@env('COSMOSDB_CONNECTION_STRING')"
  },
  "entities": {
    "Book": {
      "source": "Book",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "metadataviewer",
          "actions": ["read"]
        }
      ]
    }
  }
}

Annotazioni

Il schema percorso nel file di configurazione è relativo al percorso del file di configurazione DAB. Verificare che il file di schema GraphQL si trova nella directory corretta.

Questo $schema URL punta a una versione DAB specifica. Usare l'URL dello schema corrispondente alla versione di DAB.

Accesso al campo basato sui ruoli

Quando si utilizza la direttiva @authorize con i ruoli, considerare il modo in cui vengono assegnati i ruoli:

Scenario Assegnazione di ruolo Accesso ai @authorize campi
Richiesta anonima Nessun ruolo assegnato Negato
Richiesta autenticata authenticated Il ruolo del sistema viene assegnato automaticamente Consentito se corrisponde al ruolo
Richiesta di ruolo personalizzata Includere l'intestazione X-MS-API-ROLE con il nome del ruolo Consentito se corrisponde al ruolo

Questa tabella si applica a campi o tipi che includono @authorizein modo esplicito . Per i campi senza @authorize, le autorizzazioni a livello di entità determinano l'accesso.

Per le richieste autenticate che richiedono un ruolo personalizzato, inviare l'intestazione X-MS-API-ROLE :

GET /graphql HTTP/1.1
Host: localhost:5000
Authorization: Bearer <your-jwt-token>
X-MS-API-ROLE: metadataviewer

Query tra contenitori

Le operazioni GraphQL tra contenitori non sono supportate in Azure Cosmos DB per NoSQL.

Se si tenta di configurare relazioni tra entità in contenitori diversi usando dab add o dab update, la convalida dell'interfaccia della riga di comando non riesce.

Il messaggio di errore della CLI è: Adding/updating Relationships is currently not supported in CosmosDB.

Per informazioni dettagliate sulla configurazione delle relazioni (supportate per altri database), vedere Configurazione delle relazioni.

Risolvere le limitazioni tra contenitori

Per ovviare a questa limitazione, è consigliabile ristrutturare il modello di dati per usare documenti incorporati all'interno di un singolo contenitore. Questo approccio è spesso più efficiente per Azure Cosmos DB e si allinea alle procedure consigliate per la modellazione dei dati NoSQL.

Ad esempio, anziché separare Book e Author contenitori con relazioni:

// Embedded model in a single container
{
  "id": "book-1",
  "title": "Introduction to DAB",
  "authors": [
    {
      "firstName": "Jane",
      "lastName": "Developer"
    }
  ]
}

Per altre informazioni sulle strategie di modellazione dei dati, vedere Modellazione dei dati in Azure Cosmos DB.

Disponibilità dell'API REST

Il generatore di API dati non genera endpoint REST per Azure Cosmos DB per NoSQL perché Azure Cosmos DB offre già un'API REST nativa completa per le operazioni sui documenti.

Quando si usa DAB con Azure Cosmos DB per NoSQL, DAB espone solo gli endpoint GraphQL e non genera OpenAPI. Per accedere ai dati tramite REST, usare direttamente l'API REST di Azure Cosmos DB .

Problemi di configurazione comuni

File di schema non trovato

  • Errore: GraphQL schema file not found
  • Soluzione: assicurarsi che il schema percorso nella configurazione sia relativo al percorso del file di configurazione.

Incongruenza nel nome dell'entità

  • Errore: Entity '<name>' not found in schema
  • Soluzione: verificare che il nome dell'entità nella configurazione corrisponda esattamente alla @model(name: "...") direttiva. I nomi sono sensibili alla distinzione tra maiuscole e minuscole.

Accesso al campo non autorizzato

  • Errore: Errore di autorizzazione GraphQL (ad esempio, quando il ruolo non è consentito)
  • Soluzione: verificare che sia @authorize i ruoli che i permessi dell'entità consentano l'accesso al ruolo richiedente.

Passo successivo

Guida rapida: Usare il generatore di API per dati con NoSQL

Contenuti correlati

  • Last updated on