diff --git a/README-localized/README-es-es.md b/README-localized/README-es-es.md new file mode 100644 index 0000000..55c6923 --- /dev/null +++ b/README-localized/README-es-es.md @@ -0,0 +1,220 @@ +--- +page_type: sample +description: "Este ejemplo de Azure WebJobs muestra cómo empezar a obtener notificaciones de Microsoft Graph." +products: +- ms-graph +languages: +- csharp +extensions: + contentType: samples + technologies: + - Microsoft Graph + services: + - Users + createdDate: 5/10/2017 5:24:11 PM +--- + +# Ejemplo de webhooks de Microsoft Graph con el SDK de WebJobs +Suscríbase a [webhooks de Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) para recibir una notificación cuando se produzcan cambios en los datos del usuario, de modo que no tenga que realizar un sondeo de los cambios. + +En este ejemplo de Azure WebJobs se muestra cómo empezar a obtener notificaciones de Microsoft Graph. Microsoft Graph ofrece un punto de conexión unificado de API para obtener acceso a datos desde la nube de Microsoft. + +>Este ejemplo usa el punto de conexión de Azure AD para obtener un token de acceso para cuentas profesionales o educativas. El ejemplo usa un permiso solo de la aplicación, pero los permisos delegados también deberían funcionar. + +Las tareas comunes que una aplicación realiza con las suscripciones de webhooks son las siguientes: + +- Obtener consentimiento para suscribirse a los recursos de los usuarios y después, obtener un token de acceso. +- Usar el token de acceso para [crear una suscripción](https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/subscription_post_subscriptions) a un recurso. +- Devolver un token de validación para confirmar la dirección URL de notificación. +- Escuchar las notificaciones de Microsoft Graph y responder con un código de estado 202. +- Solicitar más información sobre los recursos modificados utilizando los datos en la notificación. + +Después de que la aplicación cree una suscripción con el token de autenticación solo para la aplicación, Microsoft Graph envía una notificación al extremo de notificaciones registrado cuando se produce un evento en los datos del usuario. Entonces, la aplicación reaccionará al evento. + +Este ejemplo está suscrito al recurso de `usuarios` para cambios `actualizados` y `eliminados`. En el ejemplo se presupone que la dirección URL de notificación es una [función de Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview), que escucha el webhook en http e inmediatamente agrega las notificaciones a una cola de almacenamiento de Azure. El ejemplo usa el [SDK de Azure WebJobs](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) para enlazar con la cola de almacenamiento de Azure y recibir notificaciones nuevas a medida que se ponen en cola por la función de Azure. + +## Requisitos previos + +Para usar el ejemplo de Webhooks de Microsoft Graph con el SDK de WebJobs, necesita lo siguiente: + +* Visual Studio 2017 instalado en el equipo de desarrollo. + +* Una [cuenta profesional o educativa](http://dev.office.com/devprogram). + +* El Id. de la aplicación y la clave que [registró en el Portal de Azure](#register-the-app). + +* Un extremo HTTPS público para recibir y enviar solicitudes HTTP. Puede hospedar esto en Microsoft Azure u otro servicio. Este ejemplo se ha probado con [Función de Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) + +* Una cuenta de almacenamiento de Azure que usará el [SDK de Azure WebJobs](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) + +### Crear su aplicación + +#### Elija el inquilino en el que desea crear su aplicación + +1. Inicie sesión en el [Portal de Azure](https://portal.azure.com) con una cuenta profesional o educativa. +1. Si su cuenta se encuentra en más de un inquilino de Azure AD: + 1. Seleccione su perfil en el menú de la esquina superior derecha de la página y después, elija **Cambiar directorio**. + 1. Cambie su sesión al inquilino de Azure AD donde quiera crear su aplicación. + +#### Registrar la aplicación + +1. Vaya al [Microsoft Azure Portal > Registro de aplicaciones](https://go.microsoft.com/fwlink/?linkid=2083908) para registrar su aplicación. +![Registro de la aplicación](readme-images/aad-app-registration.PNG) +1. Haga clic en **Nuevo registro**. +![Registro de la aplicación](readme-images/aad-new-registration.PNG) +1. Cuando aparezca la página **Registrar una aplicación**, introduzca la información de registro de su aplicación: + 1. En la sección **Nombre**, escriba un nombre significativo que se mostrará a los usuarios de la aplicación. Por ejemplo: `MyWebApp` + 1. En la sección **Tipos de cuentas admitidas**, seleccione **Cuentas en cualquier directorio organizacional y cuentas personales de Microsoft (por ejemplo, Skype, Xbox, Outlook.com)**. +1. Seleccione **Registrar** para crear la aplicación. +![Registrar una aplicación](readme-images/aad-register-an-app.png) +1. En la página **Información general** de la aplicación, busque el valor **Id. de la aplicación (cliente)** y guárdelo para más tarde. Necesitará este valor para configurar el archivo de configuración de Visual Studio para este proyecto. +![Id. de aplicación](readme-images/aad-application-id.PNG) +1. En la lista de páginas de la aplicación, seleccione **Autenticación**. + 1. En la sección **URI de redirección**, seleccione **Web** en el cuadro combinado y escriba los siguientes URI de redirección: + - `https://mysigninurl` + ![URI de redireccionamiento](readme-images/aad-redirect-uri.PNG) +1. Seleccione **Guardar**. +1. En la página **Certificados y secretos**, en la sección **Secretos de cliente**, elija **Nuevo secreto de cliente**. + 1. Escriba una descripción de clave (de la instancia `app secret`). + 1. Seleccione una duración de clave de **En un año**, **En 2 años** o **Nunca expira**. + ![Secreto de cliente](readme-images/aad-new-client-secret.png) + 1. Cuando haga clic en el botón **Agregar**, se mostrará el valor de clave. Copie el valor de clave y guárdelo en una ubicación segura. + ![Secreto de cliente](readme-images/aad-copy-client-secret.png) + Necesitará esta clave más tarde para configurar el proyecto en Visual Studio. Este valor de clave no se volverá a mostrar, ni se podrá recuperar por cualquier otro medio, por lo que deberá registrarlo tan pronto como sea visible desde Microsoft Azure Portal. + + +1. En la lista de páginas de la aplicación, seleccione **Permisos de API**. + 1. Haga clic en el botón **Agregar un permiso** y después, asegúrese de que la pestaña **API de Microsoft** esté seleccionada. + 1. En la sección **API de Microsoft más usadas**, seleccione **Microsoft Graph**. + 1. En la sección **Permisos de aplicación**, asegúrese de que el permiso **Directory.Read.All** está activado. Si es necesario, use el cuadro de búsqueda. + 1. Seleccione el botón **Agregar permisos**. + +1. En la página **Administrar**, seleccione **Permisos de API** > **Agregar un permiso**. + + ![Una captura de pantalla de Seleccionar permisos de API](readme-images/aad-api-permissions.PNG) + +1. Elija **API de Microsoft** > **Microsoft Graph**. + + ![Una captura de pantalla de Solicitar permisos de API](readme-images/aad-request-api-permissions.PNG) + +1. Elija **Permisos de aplicación**. En el cuadro de búsqueda, escriba **directory.read.all** y seleccione la primera opción de la lista. Seleccione **Agregar permisos**. + + ![Una captura de pantalla de permisos delegados](readme-images/aad-application-permissions.PNG) + + +## Configurar Función de Azure +Debe exponer un extremo HTTPS público para crear una suscripción y recibir notificaciones de Microsoft Graph. Puede usar Azure Functions para lo mismo. + +1. Inicie sesión en el [Portal de Azure](https://portal.azure.com/) con una cuenta profesional o educativa. + +2. Elija **aplicaciones de función** en el panel de navegación de la parte izquierda. + +3. Siga las instrucciones para crear una nueva **aplicación de función** + +4. Crear una nueva función **WebHook/API** con el siguiente código de muestra + +```csharp +using System.Net; + +public static async Task Run(HttpRequestMessage req, ICollector queue, TraceWriter log) +{ + log.Info("C# HTTP trigger function processed a request."); + + // parse query parameter + string validationToken = req.GetQueryNameValuePairs() + .FirstOrDefault(q => string.Compare(q.Key, "validationToken", true) == 0) + .Value; + + log.Info("validationToken: " + validationToken); + + // Get request body + string data = await req.Content.ReadAsStringAsync(); + + log.Info("Body of request: " + data); + + queue.Add(data); + + log.Info("Added message to queue"); + + return string.IsNullOrWhiteSpace(validationToken) + ? req.CreateResponse(HttpStatusCode.Accepted, "Notification received") + : req.CreateResponse(HttpStatusCode.OK, validationToken); +} +``` + +5. Elija **Integrar** > **Nueva salida** > **Almacenamiento de cola de Azure ** + +6. Escriba `queue` como **nombre de parámetro de mensaje** + +7. Escriba `webhooksnotificationqueue` como **nombre de cola** + +8. Use una **conexión de cuenta de almacenamiento** existente o cree una nueva + +9. Elija la función creada y **Ejecutar** desde el portal para asegurarse de que funciona correctamente. + +10. Elija **Obtener dirección URL de la función** para copiar la dirección URL de notificación que se usará en el ejemplo. + +## Configurar proyecto de ejemplo + +1. En el explorador de soluciones, seleccione el proyecto **App.config** + + a. Para la clave **ClientId**, reemplace *ENTER_YOUR_APP_ID* con el Id. de aplicación de la aplicación de Azure registrada. + + b. Para la clave **ClientSecret**, reemplace *ENTER_YOUR_SECRET* con la clave de la aplicación de Azure registrada. + + c. Para la clave **tenantId**, reemplace *ENTER_YOUR_ORGANIZATION_ID* con el ID. de su organización. + + d. Para la clave **webjobs**, reemplace *ENTER_YOUR_AZURE_STORAGE_CONNECTION_STRING* por la cadena de conexión de almacenamiento de Azure integrada en la función Azure. + + e. Para la clave **notificationurl**, reemplace *ENTER_YOUR_NOTIFICATION_URL* por la dirección URL de la función de Azure. + +## Usar la aplicación de ejemplo +1. Para iniciar el ejemplo, presione **F5**. + +2. Espere a que la muestra imprima el mensaje **nueva suscripción creada con ID.:** + +3. Actualice las propiedades de cualquier usuario de la organización. Ejemplo: Actualizar el número de teléfono + +4. En unos minutos, la muestra debería recibir la notificación para el usuario actualizado, así como su identificación. + +5. Cada 30 segundos, el ejemplo renovará la suscripción. Se puede cambiar el período de tiempo de la operación actualizada para que sea cada 24 horas. + +## Componentes clave del ejemplo + +**Controladores** +- [`Function.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/Functions.cs) administra las suscripciones y recibe las notificaciones. +- [`Program.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/SubscriptionController.cs) arranca el host de Azure WebJob. + +## Solución de problemas + +| Problema | Resolución | +|:------|:------| +| Recibe una respuesta 403 Prohibido al intentar crear una suscripción. | Asegúrese de que el registro de su aplicación incluya el permiso de la aplicación **Read directory data** para Microsoft Graph (como se describe en la sección [Registrar la aplicación](#register-the-app)). | +| No recibe notificaciones. | Consulte los registros para la función de Azure en [portal](https://portal.azure.com/). Si Microsoft Graph no está enviando las notificaciones, abra una incidencia con la etiqueta[Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph) en *[MicrosoftGraph]*. Incluya el ID. de suscripción y la hora en que se creó.

| +| Recibe una respuesta de *Se ha agotado el tiempo de espera de la solicitud de validación de suscripción*. | Esto indica que Microsoft Graph no recibió una respuesta de validación en el intervalo de tiempo esperado (10 segundos).

Si creó la función de Azure en **plan de consumo**, la función puede entrar en suspensión por inactividad. El ejemplo probará de nuevo y debería tener éxito en los siguientes intentos. Asimismo, pruebe a crear una función de Azure con el plan de App Service. | +| Recibe errores durante la instalación de los paquetes | Asegúrese de que la ruta de acceso local donde colocó la solución no es demasiado larga o profunda. Para resolver este problema, mueva la solución más cerca de la unidad raíz. | + + +## Colaboradores ## + +Si quiere hacer su aportación a este ejemplo, vea [CONTRIBUTING.MD](/CONTRIBUTING.md). + +Este proyecto ha adoptado el [Código de conducta de código abierto de Microsoft](https://opensource.microsoft.com/codeofconduct/). Para obtener más información, vea [Preguntas frecuentes sobre el código de conducta](https://opensource.microsoft.com/codeofconduct/faq/) o póngase en contacto con [opencode@microsoft.com](mailto:opencode@microsoft.com) si tiene otras preguntas o comentarios. + +## Preguntas y comentarios + +Nos encantaría recibir sus comentarios sobre Webhooks de Microsoft Graph con el SDK de WebJobs. Puede enviarnos sus preguntas y sugerencias a través de la sección [Problemas](https://github.com/microsoftgraph/webjobs-webhooks-sample/issues) de este repositorio. + +Las preguntas sobre Microsoft Graph en general deben publicarse en [Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph). Asegúrese de que sus preguntas o comentarios estén etiquetados con *[MicrosoftGraph]*. + +Si quiere sugerir alguna función, publique su idea en nuestra página de [User Voice](https://officespdev.uservoice.com/) y vote por sus sugerencias. + +## Recursos adicionales + +* [Ejemplo de webhooks de Microsoft Graph Node.js](https://github.com/microsoftgraph/nodejs-webhooks-rest-sample) +* [Trabajar con webhooks en Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) +* [Recurso de suscripción](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/subscription) +* [Sitio para desarrolladores de Microsoft Graph](https://developer.microsoft.com/en-us/graph/) +* [Llamar a Microsoft Graph desde una aplicación de ASP.NET MVC](https://developer.microsoft.com/en-us/graph/docs/platform/aspnetmvc) + +Copyright (c) 2019 Microsoft Corporation. Todos los derechos reservados. diff --git a/README-localized/README-fr-fr.md b/README-localized/README-fr-fr.md new file mode 100644 index 0000000..f9bc483 --- /dev/null +++ b/README-localized/README-fr-fr.md @@ -0,0 +1,220 @@ +--- +page_type: sample +description: "Cet exemple Azure WebJobs montre comment commencer à recevoir des notifications de Microsoft Graph." +products: +- ms-graph +languages: +- csharp +extensions: + contentType: samples + technologies: + - Microsoft Graph + services: + - Users + createdDate: 5/10/2017 5:24:11 PM +--- + +# Exemple de Webhooks Microsoft Graph à l’aide d’un kit de développement logiciel (SDK) WebJobs +Abonnez-vous à des [webhooks Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) pour être averti lorsque les données de vos utilisateurs changent, de sorte que vous n’avez pas besoin d’interroger les modifications. + +Cet exemple Azure WebJobs montre comment commencer à recevoir des notifications de Microsoft Graph. Microsoft Graph fournit un point de terminaison d’API unifiée pour accéder aux données à partir de Microsoft Cloud. + +>Cet exemple utilise le point de terminaison Azure AD pour obtenir un jeton d’accès pour les comptes professionnels ou scolaires. L’exemple utilise une autorisation uniquement pour les applications, mais les autorisations déléguées doivent fonctionner également. + +Voici les tâches courantes qu’une application effectue avec des abonnements webhook : + +- Obtenir le consentement pour vous abonner aux ressources des utilisateurs, puis obtenir un jeton d’accès. +- Utiliser le jeton d'accès pour [créer un abonnement](https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/subscription_post_subscriptions) à une ressource. +- Renvoyer un jeton de validation pour confirmer l'URL de notification. +- Écouter les notifications de Microsoft Graph et répondre avec un code d’état 202. +- Demander plus d’informations sur les ressources modifiées à l’aide des données de la notification. + +Une fois que l'application a créé un abonnement à l’aide du jeton d’accès à authentification application uniquement, Microsoft Graph envoie une notification au terminal enregistré lorsque des événements se produisent dans les données de l'utilisateur. L’application réagit ensuite à l’événement. + +Cet exemple s’abonne à la ressource`Utilisateurs` pour les changements `mis à jour` et `supprimés`. Cet exemple part du principe que l’URL de notification est une [fonction Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview), qui écoute les webhook sur http et ajoute immédiatement ces notifications à une file d’attente de stockage Azure. L’exemple utilise [SDK Azure WebJobs](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) pour se lier à la file d’attente de stockage Azure et recevoir de nouvelles notifications, telles qu’elles sont mises en file d’attente par la fonction Azure. + +## Conditions préalables + +Pour utiliser l’exemple Microsoft Graph Webhooks à l’aide d’un SDK WebJobs, vous avez besoin des éléments suivants : + +* Visual Studio 2017 installé sur votre ordinateur de développement. + +* Un [compte professionnel ou scolaire](http://dev.office.com/devprogram). + +* ID de l’application et clé de l’application que vous [inscrivez sur le portail Azure](#register-the-app). + +* Un point de terminaison public HTTPS pour recevoir et envoyer des demandes HTTP. Vous pouvez héberger celui-ci sur Microsoft Azure ou un autre service. Cet exemple a été testé à l’aide de la [fonction Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) + +* Un compte de stockage Azure qui sera utilisé par le [Kit de développement de Azure WebJobs](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) + +### Créer votre application + +#### Sélectionnez le locataire dans lequel vous voulez créer votre application + +1. Connectez-vous au [Portail Microsoft Azure](https://portal.azure.com) à l’aide d’un compte professionnel ou scolaire. +1. Si votre compte est présent dans plusieurs locataires Azure AD : + 1. Sélectionnez votre profil dans le menu situé dans le coin supérieur droit de la page, puis **Basculer entre les répertoires**. + 1. Sélectionnez le locataire Azure AD dans lequel vous souhaitez créer votre application. + +#### Inscription de l’application + +1. Accédez au [Portail Microsoft Azure > enregistrement des applications](https://go.microsoft.com/fwlink/?linkid=2083908) pour enregistrer votre application. +![Inscription de l’application](readme-images/aad-app-registration.PNG) +1. Sélectionnez **Nouvelle inscription**. +![Inscription de l’application](readme-images/aad-new-registration.PNG) +1. Lorsque la **page Inscrire une application** s’affiche, saisissez les informations d’inscription de votre application : + 1. Dans la section **Nom**, saisissez un nom explicite qui s’affichera pour les utilisateurs de l’application. Par exemple : `MyWebApp` + 1. Dans la section **Types de comptes pris en charge**, sélectionnez **Comptes dans un annuaire organisationnel et comptes personnels Microsoft (par ex. Skype, Xbox, Outlook.com)**. +1. Sélectionnez **S’inscrire** pour créer l’application. +![Inscrire une application](readme-images/aad-register-an-app.png) +1. Sur la page **Vue d’ensemble** de l’application, notez la valeur **ID d’application (client)** et conservez-la pour plus tard. Vous aurez besoin de cette valeur pour paramétrer le fichier de configuration de Visual Studio pour ce projet. +![ID de l’application](readme-images/aad-application-id.PNG) +1. Dans la liste des pages de l’application, sélectionnez **Authentification**. + 1. Dans la section **URI de redirection**, sélectionnez **Web** dans la zone de liste déroulante et entrez les URI de redirection suivants : + - `https://mysigninurl` + ![de redirection d’URI](readme-images/aad-redirect-uri.PNG) +1. Sélectionnez **Enregistrer**. +1. Dans la page **Certificats et clés secrètes**, dans la section **Clés secrètes de clients**, sélectionnez **Nouvelle clé secrète client**. + 1. Entrez une description de clé (par exemple `clé secrète de l’application`), + 1. Sélectionnez une durée de clé : **Dans 1 an**, **Dans 2 ans** ou **N’expire jamais**. + ![Clé secrète client](readme-images/aad-new-client-secret.png) + 1. Lorsque vous cliquez sur le bouton **Ajouter**, la valeur de la clé s’affiche. Copiez la clé et enregistrez-le dans un endroit sûr. + ![Clé secrète client](readme-images/aad-copy-client-secret.png) + Vous aurez besoin de cette clé ultérieurement pour configurer le projet dans Visual Studio. Cette valeur de clé ne sera plus affichée, ni récupérée par d’autres moyens. Par conséquent, enregistrez-la dès qu’elle est visible depuis le Portail Microsoft Azure. + + +1. Dans la liste des pages de l’application, sélectionnez **Permissions API**. + 1. Cliquez sur le bouton **Ajouter une autorisation**, puis assurez-vous que l’onglet **Microsoft APIs** est sélectionné. + 1. Dans la section **API Microsoft couramment utilisées**, sélectionnez **Microsoft Graph**. + 1. Dans la section **Autorisations applicatives**, assurez-vous que l’autorisation **Directory.Read.All** est activée. Utilisez la zone de recherche, le cas échéant. + 1. Cliquez sur le bouton **Ajouter des autorisations**. + +1. Dans la page **Gérer**, sélectionnez **Autorisations API** > **Ajouter une autorisation**. + + ![Capture d’écran des autorisations de sélection API](readme-images/aad-api-permissions.PNG) + +1. Sélectionnez **API Microsoft** > **Microsoft Graph**. + + ![Capture d’écran des autorisations de requête API](readme-images/aad-request-api-permissions.PNG) + +1. Sélectionnez **Autorisations de l’application**. Dans la zone de recherche, tapez **directory.read.all** et sélectionnez la première option dans la liste. Sélectionnez **Ajouter des autorisations**. + + ![Capture d’écran des autorisations déléguées](readme-images/aad-application-permissions.PNG) + + +## Configurer la fonction Azure +Vous devez exposer un point de terminaison public HTTPS pour créer un abonnement et recevoir des notifications de Microsoft Graph. Vous pouvez utiliser les fonctions Azure pour ceci. + +1. Connectez-vous au [Portail Azure](https://portal.azure.com/) à l’aide d’un compte professionnel ou scolaire. + +2. Sélectionnez **Applications fonction** dans le volet de navigation gauche. + +3. Suivez les instructions pour créer une nouvelle **application de fonction** + +4. Créez une nouvelle fonction**Webhook/API** à l’aide de l’exemple de code suivant + +```csharp +using System.Net; + +public static async Task Run(HttpRequestMessage req, ICollector queue, TraceWriter log) +{ + log.Info("C# HTTP trigger function processed a request."); + + // parse query parameter + string validationToken = req.GetQueryNameValuePairs() + .FirstOrDefault(q => string.Compare(q.Key, "validationToken", true) == 0) + .Value; + + log.Info("validationToken: " + validationToken); + + // Get request body + string data = await req.Content.ReadAsStringAsync(); + + log.Info("Body of request: " + data); + + queue.Add(data); + + log.Info("Added message to queue"); + + return string.IsNullOrWhiteSpace(validationToken) + ? req.CreateResponse(HttpStatusCode.Accepted, "Notification received") + : req.CreateResponse(HttpStatusCode.OK, validationToken); +} +``` + +5. Sélectionnez **Intégrer** > **Nouvelle sortie** > **Espace de stockage file d’attente Azure** + +6. Entrez `file d’attente` comme **nom du paramètre de message** + +7. Entrez `webhooksnotificationqueue` comme nom de **la file d’attente** + +8. Utiliser une nouvelle ou existante **connexion à un compte de stockage** + +9. Sélectionnez la fonction créée et**Exécutez** à partir du portail pour vérifier qu’elle réussit. + +10. Sélectionnez **Obtenir l’URL de la fonction** pour copier l’URL de notification à utiliser dans l’exemple. + +## Exemple de projet de configuration + +1. Dans l’Explorateur de solutions, sélectionnez le projet **App.config**. + + a. Pour la clé **clientId**, remplacez *ENTER_YOUR_APP_ID* par l’ID d’application de votre application Azure inscrite. + + b. Pour la clé**clientSecret**, remplacez *ENTER_YOUR_SECRET* par la clé de votre application Azure enregistrée. + + c. Pour la clé de **tenantId**, remplacez *ENTER_YOUR_ORGANIZATION_ID* par l’ID de votre organisation. + + d. Pour la clé **webjobs**, remplacez *ENTER_YOUR_AZURE_STORAGE_CONNECTION_STRING* par une chaîne de connexion de l’espace de stockage Azure intégrée dans la fonction Azure. + + e. Pour la clé **notificationURL**, remplacez *ENTER_YOUR_NOTIFICATION_URL* par l’URL de la fonction Azure. + +## Utiliser l’exemple d’application +1. Appuyez sur **F5** pour démarrer votre exemple. + +2. Attendez que l’exemple imprime le message **Créer un nouvel abonnement avec ID :** + +3. Mettre à jour les propriétés d’un utilisateur de l’organisation. Exemple : Mettre à jour son numéro de téléphone + +4. Sous quelques minutes, l’exemple doit recevoir une notification pour l’utilisateur mis à jour avec son identification. + +5. Toutes les 30 secondes, l’échantillon renouvelle l’abonnement. Vous pouvez modifier la durée de l’opération mise à jour pour qu’elle soit effectuée toutes les 24 heures. + +## Composants clés de l’exemple + +**Contrôleurs** +-[`Function.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/Functions.cs) gère les abonnements et reçoit les notifications. +-[`Program.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/SubscriptionController.cs) amorce l’hôte Azure WebJob. + +## Résolution des problèmes + +| Problème | Résolution | +| :------| :------| +| Vous obtenez une réponse 403 Interdit lorsque vous essayez de créer un abonnement. | Assurez-vous que l’inscription de l’application inclut l’autorisation d’application **Read directory data** pour Microsoft Graph (comme décrit dans la section [Inscrire l’application](#register-the-app)) | +| Vous ne recevez pas de notifications. | Consultez les journaux pour la fonction Azure dans le[portail](https://portal.azure.com/). Si Microsoft Graph n’envoie pas de notifications, veuillez ouvrir un problème de dépassement de capacité de la pile marqué*[MicrosoftGraph]*. Incluez l’ID de l’abonnement et l’heure à laquelle il a été créé.

| +| Vous recevez une réponse *La demande de validation d’abonnement a expiré*. | Cela indique que Microsoft Graph n’a pas reçu de réponse de validation dans le délai prévu (environ 10 secondes).

Si vous avez créé une fonction Azure sur **régime de consommation**, la fonction peut être mise en veille en raison de l’inactivité. L’exemple réessaiera et devrait réussir dans les prochaines tentatives. Vous pouvez également essayer de créer une fonction Azure à l’aide du plan de service d’application. | +| Vous recevez des erreurs pendant l’installation des packages. | vérifiez que le chemin d’accès local où vous avez sauvegardé la solution n’est pas trop long/profond. Pour résoudre ce problème, il vous suffit de déplacer la solution dans un dossier plus près du répertoire racine de lecteur. | + + +## Contribution ## + +Si vous souhaitez contribuer à cet exemple, voir [CONTRIBUTING.MD](/CONTRIBUTING.md). + +Ce projet a adopté le [code de conduite Open Source de Microsoft](https://opensource.microsoft.com/codeofconduct/). Pour en savoir plus, reportez-vous à la [FAQ relative au code de conduite](https://opensource.microsoft.com/codeofconduct/faq/) ou contactez [opencode@microsoft.com](mailto:opencode@microsoft.com) pour toute question ou tout commentaire. + +## Questions et commentaires + +N’hésitez pas à nous faire part de vos commentaires sur l’exemple de webhooks Microsoft Graph utilisant le kit de développement logiciel webjobs. Vous pouvez nous faire part de vos questions et suggestions dans la rubrique [Problèmes](https://github.com/microsoftgraph/webjobs-webhooks-sample/issues) de ce référentiel. + +Les questions générales sur Microsoft Graph doivent être publiées sur la page [Dépassement de capacité de la pile](https://stackoverflow.com/questions/tagged/MicrosoftGraph). Veillez à poser vos questions ou à rédiger vos commentaires en utilisant les tags *[MicrosoftGraph]*. + +Si vous avez des suggestions de fonctionnalité, soumettez votre idée sur notre page [Voix utilisateur](https://officespdev.uservoice.com/) et votez pour votre suggestion. + +## Ressources supplémentaires + +* [Exemple de Webhooks Microsoft Graph Node.js](https://github.com/microsoftgraph/nodejs-webhooks-rest-sample) +* [Utiliser des Webhooks dans Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) +* [Ressource abonnement](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/subscription) +* [Site des développeurs de Microsoft Graph](https://developer.microsoft.com/en-us/graph/) +* [Appel de Microsoft Graph dans une application ASP.NET MVC](https://developer.microsoft.com/en-us/graph/docs/platform/aspnetmvc) + +Copyright (c) 2019 Microsoft Corporation. Tous droits réservés. diff --git a/README-localized/README-ja-jp.md b/README-localized/README-ja-jp.md new file mode 100644 index 0000000..363d567 --- /dev/null +++ b/README-localized/README-ja-jp.md @@ -0,0 +1,220 @@ +--- +page_type: sample +description: "この Azure WebJobs サンプルは、Microsoft Graph から通知を取得する方法を示しています。" +products: +- ms-graph +languages: +- csharp +extensions: + contentType: samples + technologies: + - Microsoft Graph + services: + - Users + createdDate: 5/10/2017 5:24:11 PM +--- + +# WebJobs SDK を使用した Microsoft Graph Webhook のサンプル +[Microsoft Graph webhook](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) をサブスクライブすると、ユーザーのデータが変更された場合に通知を受け取ることができ、変更内容についてポーリングを行う必要がなくなります。 + +この Azure WebJobs サンプルでは、Microsoft Graph からの通知の取得を開始する方法を示します。Microsoft Graph は、Microsoft クラウドのデータにアクセスするための統合 API エンドポイントを提供します。 + +>このサンプルは Azure AD エンドポイントを使用して、職場または学校のアカウントのアクセス トークンを取得します。このサンプルでは、アプリケーションのみのアクセス許可を使用します。ただし、委任されたアクセス許可も機能します。 + +アプリケーションが Webhook のサブスクリプションを使用して実行する一般的なタスクを次に示します。 + +- ユーザーのリソースをサブスクライブするための同意を取得し、アクセス トークンを取得する。 +- アクセス トークンを使用して、リソースへの[サブスクリプションを作成](https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/subscription_post_subscriptions)する。 +- 検証トークンを送り返して通知 URL を確認する。 +- Microsoft Graph からの通知をリッスンし、状態コード 202 で応答する。 +- 通知内のデータを使用して、変更されたリソースの詳細情報を要求する。 + +アプリがアプリ専用の認証トークンを使用してサブスクリプションを作成した後、ユーザーのデータでイベントが発生すると、Microsoft Graph は登録済み通知エンドポイントに通知を送信します。これに対して、アプリがイベントに反応します。 + +このサンプルは、`更新`および`削除`された変更の `Users` リソースをサブスクライブします。サンプルでは、​​通知 URL が [Azure 関数](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview)であり、Webhook over http をリッスンし、それらの通知を Azure ストレージ キューにすぐに追加すると想定しています。サンプルでは、[Azure WebJobs SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) を使用して Azure ストレージ キューにバインドし、Azure 関数によってキューに入ったときに新しい通知を受信します。 + +## 前提条件 + +WebJobs SDK を使用して Microsoft Graph Webhooks サンプルを使用するには、次のものが必要です。 + +* 開発用コンピューターにインストールされている Visual Studio 2017。 + +* [職場または学校のアカウント](http://dev.office.com/devprogram)。 + +* [Azure ポータルに登録](#register-the-app)するアプリケーションのアプリケーション ID とキー。 + +* HTTP 要求を送受信するためのパブリック HTTPS エンドポイント。Microsoft Azure または別のサービスでこれをホストできます。このサンプルは [Azure 関数](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview)を使用してテストされました。 + +* [Azure WebJobs SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) で使用される Azure ストレージ アカウントです。 + +### アプリを作成する + +#### アプリを作成するテナントを選択する + +1. 職場または学校のアカウントを使用して、[Azure ポータル](https://portal.azure.com)にサインインします。 +1. 複数の Azure AD テナントにアカウントが存在する場合: + 1. ページの右上隅にあるメニューからプロファイルを選択し、[**ディレクトリの切り替え**] を選択します。 + 1. アプリケーションを作成する Azure AD テナントにセッションを変更します。 + +#### アプリを登録する + +1. [[Azure ポータル]、[アプリの登録]](https://go.microsoft.com/fwlink/?linkid=2083908) の順に移動してアプリを登録します。 +![アプリケーションの登録](readme-images/aad-app-registration.PNG) +1. [**新規登録**] を選択します。 +![アプリケーションの登録](readme-images/aad-new-registration.PNG) +1. [**アプリケーションの登録ページ**] が表示されたら、以下のアプリの登録情報を入力します。 + 1. [**名前**] セクションに、アプリのユーザーに表示されるわかりやすい名前を入力します。次に例を示します。`MyWebApp` + 1. [**サポートされているアカウントの種類**] セクションで、[**組織ディレクトリ内のアカウントと個人の Microsoft アカウント (例: Skype、Xbox、Outlook.com)**] を選択します。 +1. [**登録**] を選択して、アプリを作成します。 +![アプリを登録します](readme-images/aad-register-an-app.png) +1. アプリの [**概要**] ページで、[**Application (client) ID**] (アプリケーション (クライアント) ID) の値を確認し、後で使用するために記録します。この値は、このプロジェクトで Visual Studio 構成ファイルを設定するのに必要になります。 +![アプリケーション ID](readme-images/aad-application-id.PNG) +1. アプリのページの一覧から [**認証**] を選択します。 + 1. [**リダイレクト URI**] セクションで、コンボ ボックスの [**Web**] を選択し、次のリダイレクト URI を入力します。 + - `https://mysigninurl` + ![リダイレクト URI](readme-images/aad-redirect-uri.PNG) +1. [**保存**] を選択します。 +1. [**証明書とシークレット**] ページの [**クライアント シークレット**] セクションで、[**新しいクライアント シークレット**]を選択します。 + 1. キーの説明を入力します (例: `アプリ シークレット`)。 + 1. [**1 年**]、[**2 年**]、または [**有効期限なし**] からキーの期間を選択します。 + ![クライアントの秘密情報](readme-images/aad-new-client-secret.png) + 1. [**追加**] ボタンをクリックすると、キー値が表示されます。キー値をコピーして安全な場所に保存します。 + ![クライアント シークレット](readme-images/aad-copy-client-secret.png) + Visual Studio でプロジェクトを構成するには、このキーが必要になります。このキー値は二度と表示されず、他の方法で取得することもできませんので、Azure ポータルで表示されたらすぐに記録してください。 + + +1. アプリのページの一覧から [**API のアクセス許可**] を選択します。 + 1. [**アクセス許可の追加**] ボタンをクリックして、[**Microsoft API**] タブが選択されていることを確認します。 + 1. [**一般的に使用される Microsoft API**] セクションで、[**Microsoft Graph**] を選択します。 + 1. [**アプリケーションのアクセス許可**] セクションで、**Directory.Read.All** アクセス許可が選択されていることを確認します。必要に応じて検索ボックスを使用します。 + 1. [**アクセス許可の追加**] ボタンを選択します。 + +1. [**管理**] ページで、[**API アクセス許可**]、[**アクセス許可の追加**] の順に選択します。 + + ![[API アクセス許可] を選択したスクリーンショット](readme-images/aad-api-permissions.PNG) + +1. [**Microsoft API**]、[**Microsoft Graph**] の順に選択します。 + + ![[API のアクセス許可] を要求するスクリーンショット](readme-images/aad-request-api-permissions.PNG) + +1. [**アプリケーションのアクセス許可**] を選択します。[検索] ボックスに **directory.read.all** を入力し、リストから最初のオプションを選択します。[**アクセス許可の追加**] を選択します。 + + ![委任されたアクセス許可のスクリーンショット](readme-images/aad-application-permissions.PNG) + + +## Azure 関数のセットアップ +サブスクリプションを作成し、Microsoft Graph から通知を受信するには、パブリック HTTPS エンドポイントを公開する必要があります。Azure 関数は、同じく使用できます。 + +1. 職場または学校のアカウントを使用して、[Azure Portal](https://portal.azure.com/) にサインインします。 + +2. 左側のナビゲーション ウィンドウにある [**関数アプリ**] を選択します。 + +3. 指示に従って新しい**関数アプリ**を作成します。 + +4. 次のサンプル コードを使用して、新しい **WebHook/API** 関数を作成します。 + +```csharp +using System.Net; + +public static async Task Run(HttpRequestMessage req, ICollector queue, TraceWriter log) +{ + log.Info("C# HTTP trigger function processed a request."); + + // parse query parameter + string validationToken = req.GetQueryNameValuePairs() + .FirstOrDefault(q => string.Compare(q.Key, "validationToken", true) == 0) + .Value; + + log.Info("validationToken: " + validationToken); + + // Get request body + string data = await req.Content.ReadAsStringAsync(); + + log.Info("Body of request: " + data); + + queue.Add(data); + + log.Info("Added message to queue"); + + return string.IsNullOrWhiteSpace(validationToken) + ? req.CreateResponse(HttpStatusCode.Accepted, "Notification received") + : req.CreateResponse(HttpStatusCode.OK, validationToken); +} +``` + +5. [**統合**]、[**新規出力**]、[**Azure Queue Storage**] の順に選択します。 + +6. [**メッセージ パラメーター名**] として `queue` を入力します。 + +7. [**キュー名**] として `webhooksnotificationqueue` を入力します。 + +8. 既存のものを使用するか、新しい [**ストレージ アカウント接続**] を作成します。 + +9. 作成された関数を選択し、ポータルから [**実行**] して、正常に動作することを確認します。 + +10. [**関数 URL を取得する**] を選択して、サンプルに使用する通知 URL をコピーします。 + +## セットアップ サンプル プロジェクト + +1. ソリューション エクスプローラーで、**App.config** プロジェクトを選択します。 + + a.**clientId** キーは、*ENTER_YOUR_APP_ID* を登録済み Azure アプリケーションのアプリケーション ID で置き換えます。 + + b.**clientSecret** キーは、*ENTER_YOUR_SECRET* を登録済み Azure アプリケーションのキーで置き換えます。 + + c.**tenantId** キーは、*ENTER_YOUR_ORGANIZATION_ID* を組織 ID で置き換えます。 + + d.**webjobs** キーは、*ENTER_YOUR_AZURE_STORAGE_CONNECTION_STRING* を Azure関数に統合された Azure ストレージの接続文字列で置き換えます。 + + e. **notificationurl** キーは、*ENTER_YOUR_NOTIFICATION_URL* を Azure 関数の URL で置き換えます。 + +## サンプル アプリを使用する +1. **F5** キーを押して、サンプルを開始します。 + +2. 「**次の ID で新しいサブスクリプションを作成しました**」というメッセージを出力するまでサンプルを待ちます。 + +3. 組織内のユーザーのプロパティを更新します。例:電話番号を更新する + +4. サンプルは数分で、更新されたユーザーとその識別情報の通知を受信する必要があります。 + +5. サンプルでは、30 秒ごとにサブスクリプションが更新されます。更新された操作の期間を 24 時間ごとに変更できます。 + +## サンプルの主な構成要素 + +**コントローラー** +- [`Function.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/Functions.cs) サブスクリプションを管理し、通知を受信します。 +- [`Program.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/SubscriptionController.cs) Azure WebJob ホストをブートストラップします。 + +## トラブルシューティング + +| 問題 | 解決方法 | +|:------|:------| +| サブスクリプションを作成しようとすると、403 禁止の応答が表示されます。 | アプリの登録に、Microsoft Graph の**ディレクトリ データを読み取る**アプリのアクセス許可が含まれていることを確認します ([[アプリの登録](#register-the-app)] セクションで説明されているように)。| +| 通知を受信できません。 | [ポータル](https://portal.azure.com/)で Azure 関数のログを確認します。Microsoft Graph で通知が送信されていない場合は、[[MicrosoftGraph]](https://stackoverflow.com/questions/tagged/MicrosoftGraph) タグの付いた*スタックオーバーフロー*問題を開いてください。サブスクリプション ID と作成時刻を含めます。

| +| [*サブスクリプション検証リクエストがタイムアウトしました*] 応答が表示されました。| これは、Microsoft Graph が予想される期間 (約 10 秒) 以内に検証応答を受信しなかったことを示します。

[**従量課金プラン**] で Azure 関数を作成した場合、関数は非アクティブのため、スリープ状態になります。サンプルは再び実行され、次の試行で成功するはずです。または、App Service プランを使用して Azure 関数を作成します。| +| パッケージのインストール中にエラーが発生します。 | ソリューションを保存したローカル パスが長すぎたり深すぎたりしていないかご確認します。この問題は、ドライブのルート近くにソリューションを移動すると解決します。 | + + +## 投稿 ## + +このサンプルに投稿する場合は、[CONTRIBUTING.MD](/CONTRIBUTING.md) を参照してください。 + +このプロジェクトでは、[Microsoft Open Source Code of Conduct (Microsoft オープン ソース倫理規定)](https://opensource.microsoft.com/codeofconduct/) が採用されています。詳細については、「[Code of Conduct の FAQ (倫理規定の FAQ)](https://opensource.microsoft.com/codeofconduct/faq/)」を参照してください。また、その他の質問やコメントがあれば、[opencode@microsoft.com](mailto:opencode@microsoft.com) までお問い合わせください。 + +## 質問とコメント + +WebJobs SDK を使用して、Microsoft Graph Webhook のサンプルに関するフィードバックをぜひお寄せください。質問や提案は、このリポジトリの「[問題](https://github.com/microsoftgraph/webjobs-webhooks-sample/issues)」セクションで送信できます。 + +Microsoft Graph 全般の質問については、「[Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph)」に投稿してください。質問やコメントには、必ず "*MicrosoftGraph*" とタグを付けてください。 + +機能に関して提案がございましたら、「[User Voice](https://officespdev.uservoice.com/)」ページでアイデアを投稿してから、その提案に投票してください。 + +## その他のリソース + +* [Microsoft Graph Node.js Webhook のサンプル](https://github.com/microsoftgraph/nodejs-webhooks-rest-sample) +* [Microsoft Graph の Webhook での作業](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) +* [サブスクリプション リソース](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/subscription) +* [Microsoft Graph 開発者向けサイト](https://developer.microsoft.com/en-us/graph/) +* [ASP.NET MVC アプリで Microsoft Graph を呼び出す](https://developer.microsoft.com/en-us/graph/docs/platform/aspnetmvc) + +Copyright (c) 2019 Microsoft Corporation.All rights reserved. diff --git a/README-localized/README-pt-br.md b/README-localized/README-pt-br.md new file mode 100644 index 0000000..2e23350 --- /dev/null +++ b/README-localized/README-pt-br.md @@ -0,0 +1,220 @@ +--- +page_type: sample +description: "Este exemplo do Azure WebJobs mostra como começar a receber notificações do Microsoft Graph." +products: +- ms-graph +languages: +- csharp +extensions: + contentType: samples + technologies: + - Microsoft Graph + services: + - Users + createdDate: 5/10/2017 5:24:11 PM +--- + +# Exemplo do Microsoft Graph Webhooks usando o SDK do WebJobs +Inscreva-se no [Microsoft Graph Webhooks](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) para ser notificado quando os dados do usuário mudarem, para que você não precise fazer enquetes de mudanças. + +Este exemplo do Azure WebJobs mostra como começar a receber notificações do Microsoft Graph. O Microsoft Graph oferece um terminal de API unificado para acessar dados da nuvem do Microsoft. + +>Este exemplo usa o terminal do Azure AD para obter um token de acesso de contas corporativas ou escolares. O exemplo usa uma permissão somente para o aplicativo, mas permissões delegadas também devem funcionar. + +A seguir, são apresentadas tarefas comuns que um aplicativo executa com assinaturas dos webhooks: + +- Obtenha consentimento para se inscrever nos recursos de usuários e receber um token de acesso. +- Use o token de acesso para [criar uma assinatura](https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/subscription_post_subscriptions) para um recurso. +- Devolva um token de validação para confirmar a URL da notificação. +- Ouça as notificações do Microsoft Graph e responda com o código de status 202. +- Solicite mais informações dos recursos alterados usando os dados da notificação. + +Depois que o aplicativo cria uma assinatura usando apenas o token de autenticação do aplicativo, o Microsoft Graph envia uma notificação para o terminal de notificação registrado quando acontecem eventos nos dados do usuário. Em seguida, o aplicativo reage ao evento. + +Este exemplo se inscreve no recurso `Usuários` para `alterações atualizadas` e ` excluídas. O exemplo supõe que a URL da notificação é uma [Função do Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) que monitora o webhook por http e adiciona imediatamente essas notificações a uma fila de armazenamento do Azure. O exemplo usa o [Azure WebJobs SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) para associar à fila de armazenamento do Azure e receber novas notificações à medida que elas são enfileiradas pela função do Azure. + +## Pré-requisitos + +Para usar o exemplo Microsoft Graph Webhooks usando o WebJobs SDK, você precisa do seguinte: + +* Visual Studio 2017 instalado no computador de desenvolvimento. + +* Uma [conta corporativa ou de estudante](http://dev.office.com/devprogram). + +* A ID do aplicativo e a chave do aplicativo que você [registra no Portal do Azure](#register-the-app). + +* Um terminal do HTTPS público para receber e enviar solicitações HTTP. Você pode hospedar isso no Microsoft Azure ou em outro serviço. Este exemplo foi testado usando a [Função do Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) + +* Uma conta de armazenamento do Azure que será usada pelo [Azure WebJobs SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) + +### Criar seu aplicativo + +#### Escolher o locatário para o qual você quer criar seu aplicativo + +1. Entre no [Portal do Azure](https://portal.azure.com) usando uma conta corporativa ou de estudante. +1. Se a sua conta estiver presente em mais de um locatário do Azure AD: + 1. Selecione seu perfil no menu no canto superior direito da página e **Alterne o diretório**. + 1. Altere sua sessão no locatário do Azure AD em que você quer criar o aplicativo. + +#### Registrar o aplicativo + +1. Navegue até o [Portal do Azure > Registros de aplicativos](https://go.microsoft.com/fwlink/?linkid=2083908) para registrar seu aplicativo. +![Registro do aplicativo](readme-images/aad-app-registration.PNG) +1. Selecione **Novo registro**. +![Registro do Aplicativo](readme-images/aad-new-registration.PNG) +1. Quando a **página Registrar um aplicativo** for exibida, insira as informações de registro do aplicativo: + 1. Na seção **Nome**, insira um nome relevante que será exibido aos usuários do aplicativo. Por exemplo: `MyWebApp` + 1. Na seção **Tipos de conta com suporte**, selecione **Contas em qualquer diretório organizacional e contas pessoais do Microsoft (por exemplo: Skype, Xbox, Outlook.com)**. +1. Selecione **Registrar** para criar o aplicativo. +![Registrar um aplicativo](readme-images/aad-register-an-app.png) +1. Na página **Visão geral** do aplicativo, encontre o valor de **ID do aplicativo (cliente)** e registre-o para usar mais tarde. Esse valor será necessário para configurar o arquivo de configuração do Visual Studio desse projeto. +![ID do Aplicativo](readme-images/aad-application-id.PNG) +1. Na lista de páginas do aplicativo, selecione **Autenticação**. + 1. Na seção **Redirecionar URIs**, selecione **Web** na caixa de combinação e digite as seguintes URIs de redirecionamento: + - `https://mysigninurl` + ![URI de redirecionamento](readme-images/aad-redirect-uri.PNG) +1. Selecione **Salvar**. +1. Na página **Certificados e segredos**, na seção **Segredos do cliente**, escolha **Novo segredo do cliente**. + 1. Insira uma descrição da chave (da instância `segredo do aplicativo`). + 1. Selecione uma duração de chave de **1 ano**, **2 anos** ou **Nunca expirará**. + ![Segredo do cliente](readme-images/aad-new-client-secret.png) + 1. Ao clicar no botão **Adicionar**, o valor da chave será exibido. Copie o valor da chave e salve-o em um local seguro. + ![Segredo do cliente](readme-images/aad-copy-client-secret.png) + Você precisará dessa chave mais tarde para configurar o projeto no Visual Studio. Esse valor da chave não será exibido novamente, nem será recuperável por nenhum outro meio, portanto, grave-o assim que estiver visível no portal do Azure. + + +1. Na lista de páginas do aplicativo, selecione **Permissões do API**. + 1. Clique no botão **Adicionar uma permissão** e verifique se a guia **APIs da Microsoft** está selecionada. + 1. Na seção **APIs mais usadas do Microsoft**, selecione **Microsoft Graph**. + 1. Na seção **Permissões do aplicativo**, certifique-se de que a permissão **Mail.Read.** está marcada. Use a caixa de pesquisa, se necessário. + 1. Selecione o botão **Adicionar permissão**. + +1. Na página **Gerenciar**, selecione **Permissões do API** > **Adicionar uma permissão**. + + ![Uma captura de tela das permissões de selecionar API](readme-images/aad-api-permissions.PNG) + +1. Escolha **API do Microsoft** > **Microsoft Graph**. + + ![Uma captura de tela das permissões de selecionar API](readme-images/aad-request-api-permissions.PNG) + +1. Selecione **Permissões do aplicativo. Na caixa de pesquisa, digite **directory.read.all** e selecione a primeira opção na lista. Selecione **Adicionar permissões**. + + ![Uma captura de tela das permissões delegadas](readme-images/aad-application-permissions.PNG) + + +## Configurar função do Azure +Você deve expor um terminal HTTPS público para criar uma assinatura e receber as notificações do Microsoft Graph. Você pode usar as funções do Azure para o mesmo. + +1. Entre no [Portal do Azure](https://portal.azure.com/) usando uma conta corporativa ou de estudante. + +2. Escolha **Aplicativos da função** no painel de navegação à esquerda. + +3. Siga as instruções para criar um novo **Aplicativo da função** + +4. Criar uma nova função **WebHook/API** com o seguinte exemplo de código + +```csharp +using System.Net; + +public static async Task Run(HttpRequestMessage req, ICollector queue, TraceWriter log) +{ + log.Info("C# HTTP trigger function processed a request."); + + // parse query parameter + string validationToken = req.GetQueryNameValuePairs() + .FirstOrDefault(q => string.Compare(q.Key, "validationToken", true) == 0) + .Value; + + log.Info("validationToken: " + validationToken); + + // Get request body + string data = await req.Content.ReadAsStringAsync(); + + log.Info("Body of request: " + data); + + queue.Add(data); + + log.Info("Added message to queue"); + + return string.IsNullOrWhiteSpace(validationToken) + ? req.CreateResponse(HttpStatusCode.Accepted, "Notification received") + : req.CreateResponse(HttpStatusCode.OK, validationToken); +} +``` + +5. Escolha integrar > Nova saída > **Azure Queue Storage** + +6. Insira `fila` como **nome do Parâmetro da mensagem** + +7. Insira `webhooksnotificationqueue` como **Nome da fila** + +8. Use uma nova **Conexão de conta de armazenamento** existente ou crie uma + +9. Escolha a função criada e **Execute** do portal para garantir que ela tenha êxito. + +10. Escolha em **Obter URL da função** para copiar a notificação a ser usada no exemplo. + +## Configure o projeto do exemplo + +1. No Gerenciador de Soluções, selecione o projeto **App.config**. + + a. Na chave **clientId**, substitua *ENTER_YOUR_APP_ID* com a ID do aplicativo registeredAzure. + + b. Na chave **ClientSecret**, substitua *ENTER_YOUR_SECRET* com a chave do seu aplicativo registeredAzure. + + c. Na chave **tenantid**, substitua *ENTER_YOUR_ORGANIZATION_ID* pela ID da sua organização. + + d. Na chave **webjobs**, substitua *ENTER_YOUR_AZURE_STORAGE_CONNECTION_STRING* com série de conexões do armazenamento azure integrado na função do Azure. + + e. Na chave **notificationurl**, substitua *ENTER_YOUR_NOTIFICATION_URL* pela URL da função do Azure. + +## Usar o aplicativo do exemplo +1. Pressione **F5** para iniciar seu exemplo. + +2. Aguarde até que o exemplo imprima a mensagem **Criou uma nova assinatura com a ID:** + +3. Atualize qualquer propriedade de qualquer usuário na organização. Exemplo: Atualizar o número de telefone + +4. Em poucos minutos, o exemplo deve receber uma notificação para o usuário atualizado junto com a respectiva identificação. + +5. A cada 30 segundos, o exemplo renovará a assinatura. Pode-se alterar o período de operação atualizado uma vez a cada 24 horas. + +## Componentes principais do exemplo + +**Controladores** +- [`Function.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/Functions.cs) Gerencia assinaturas e recebe notificações. +- [`Program.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/SubscriptionController.cs) Inicialize o organizador do Azure WebJob. + +## Solução de problemas + +| Problema | Solução | +|:------|:------| +| Você recebe uma resposta de 403 Proibido ao tentar criar uma assinatura. | Certifique-se de que o registro do aplicativo inclui a permissão do aplicativo **Mail.Read** do Microsoft Graph (como descrito na seção [Registrar o aplicativo](#register-the-app)). | +| Você não recebe notificações. | Verifique a função logs do Azure no](https://portal.azure.com/)portal[. Se o Microsoft Graph não estiver enviando notificações, abra um problema no Stack Overflow marcado com *[MicrosoftGraph]*. Inclua a ID da assinatura e o horário da criação.

| +| Você recebe uma resposta *A solicitação de validação da assinatura expirou*. | Isso indica que o Microsoft Graph não recebeu uma resposta de validação dentro do prazo esperado (de aproximadamente 10 segundos).

Se você criou a função Azure em **plano de consumo**, a função poderá ser suspensa devido a inatividade. O exemplo tentará novamente e deve ser bem-sucedido nas próximas tentativas. Como alternativa, tente criar a função Azure usando o plano de serviços do aplicativo. | +| Você recebe erros ao instalar pacotes. | Verifique se o caminho local onde você colocou a solução não é muito longo/extenso. Mover a solução para mais perto da unidade raiz resolverá esse problema. | + + +## Colaboração ## + +Se quiser contribuir para esse exemplo, confira [CONTRIBUTING.MD](/CONTRIBUTING.md). + +Este projeto adotou o [Código de Conduta de Código Aberto da Microsoft](https://opensource.microsoft.com/codeofconduct/). Para saber mais, confira as [Perguntas frequentes sobre o Código de Conduta](https://opensource.microsoft.com/codeofconduct/faq/) ou entre em contato pelo [opencode@microsoft.com](mailto:opencode@microsoft.com) se tiver outras dúvidas ou comentários. + +## Perguntas e comentários + +Gostaríamos de receber seus comentários sobre o exemplo Microsoft Graph Webhooks usando o WebJobs SDK. Você pode nos enviar perguntas e sugestões na seção [Problemas](https://github.com/microsoftgraph/webjobs-webhooks-sample/issues) deste repositório. + +Em geral, as perguntas sobre o Microsoft Graph devem ser postadas no [Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph). Verifique se suas perguntas ou comentários estão marcados com *[MicrosoftGraph]*. + +Se você tiver uma sugestão de recurso, poste sua ideia na nossa página em [Voz do Usuário](https://officespdev.uservoice.com/) e vote em suas sugestões. + +## Recursos adicionais + +* [](https://github.com/microsoftgraph/nodejs-webhooks-rest-sample)Exemplo de Microsoft Graph Node.js Webhooks +* [Trabalhando com o Webhooks no Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) +* [Recurso da assinatura](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/subscription) +* [](https://developer.microsoft.com/en-us/graph/)Site do desenvolvedor do Microsoft Graph +* [Chamar o Microsoft Graph em um aplicativo do ASP.NET MVC](https://developer.microsoft.com/en-us/graph/docs/platform/aspnetmvc) + +Direitos autorais (c) 2019 Microsoft Corporation. Todos os direitos reservados. diff --git a/README-localized/README-ru-ru.md b/README-localized/README-ru-ru.md new file mode 100644 index 0000000..8b36d85 --- /dev/null +++ b/README-localized/README-ru-ru.md @@ -0,0 +1,220 @@ +--- +page_type: sample +description: "В этом примере Azure веб-задания показано, как начать получать уведомления от Microsoft Graph." +products: +- ms-graph +languages: +- csharp +extensions: + contentType: samples + technologies: + - Microsoft Graph + services: + - Users + createdDate: 5/10/2017 5:24:11 PM +--- + +# Пример веб-перехватчиков Microsoft Graph с помощью пакета SDK веб-заданий +Подпишитесь на [веб-перехватчики Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) для получения оповещений об изменениях ваших данных пользователя, чтобы не выполнять опрос на изменения. + +В этом примере Azure веб заданий показано, как начать получать уведомления от Microsoft Graph. Microsoft Graph предоставляет единую конечную точку API для доступа к данным из Microsoft Cloud. + +>В этом примере используется конечная точка Azure AD, чтобы получить маркер доступа для рабочих или учебных учетных записей. В примере используется разрешение только для приложения, однако делегированные разрешения также должны работать. + +Ниже приведены некоторые общие задачи, выполняемые приложением при наличии подписки на веб-перехватчики: + +- Получение согласия на подписку на ресурсы пользователей, а затем получение маркера доступа. +- Использование маркера доступа, чтобы [создать подписку](https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/subscription_post_subscriptions) на ресурс. +- Возврат маркера проверки для подтверждения URL-адреса уведомления. +- Отслеживание уведомлений из Microsoft Graph и ответ с кодом состояния 202. +- Запрос дополнительных сведений об измененных ресурсах с помощью данных в уведомлении. + +После того как приложение создает подписку с использованием маркера авторизации только для приложения, Microsoft Graph отправляет уведомление зарегистрированной конечной точке уведомления, когда в данных пользователя происходят события. Приложение реагирует на событие. + +Этот образец подписывается на ресурс `Пользователи` для получения `обновленных` и `удаленных` изменений. В этом примере предполагается, что URL-адрес уведомления - это [функция Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview), которая прослушивает веб перехватчик через http и немедленно добавляет эти уведомления в очередь хранилища Azure. В этом примере используется [SDK для веб заданий Azure](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) для привязки к очереди хранилища Azure и получения новых уведомлений, так как они ставятся в очередь функцией Azure. + +## Необходимые компоненты + +Чтобы использовать пример Microsoft Graph Webhooks с использованием WebJobs SDK, вам необходимо следующее: + +* Набор инструментов Visual Studio 2017, установленный на компьютере для разработки. + +* [Рабочая или учебная учетная запись](http://dev.office.com/devprogram) + +* Идентификатор приложения и ключ из приложения, которое вы [регистрируете на портале Azure](#register-the-app). + +* Открытая конечная точка HTTPS для получения и отправки HTTP-запросов. Вы можете разместить это в Microsoft Azure или другом сервисе. Этот образец был протестирован с использованием функции [Azure](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview). + +* Учетная запись хранения Azure, которая будет использоваться [Azure веб задания SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) + +### Создание приложения + +#### Выбор клиента, в котором вы хотите создать приложение + +1. Войдите на [портал Azure](https://portal.azure.com) с помощью рабочей или учебной учетной записи. +1. Если ваша учетная запись содержится в нескольких клиентах Azure AD: + 1. Выберите профиль в меню в правом верхнем углу, а затем выберите пункт **Переключение каталога**. + 1. Измените сеанс на клиента Azure AD, в котором вы хотите создать приложение. + +#### Регистрация приложения + +1. Перейдите к пункту [Портал Microsoft Azure > Регистрации приложений](https://go.microsoft.com/fwlink/?linkid=2083908), чтобы зарегистрировать приложение. +![Регистрация приложения](readme-images/aad-app-registration.PNG) +1. Выберите **Новая регистрация**. +![Регистрация Приложения](readme-images/aad-new-registration.PNG) +1. После появления страницы **Регистрация приложения** введите сведения о регистрации для своего приложения: + 1. В разделе **Имя** введите понятное имя, которое будет отображаться для пользователей приложения. Например: `MyWebApp` + 1. В разделе **Поддерживаемые типы учетных записей** выберите **Учетные записи в любом каталоге организации и личные учетные записи Майкрософт (например, Skype, Xbox, Outlook.com)**. +1. Выберите **Зарегистрировать**, чтобы создать приложение. +![Регистрация приложения](readme-images/aad-register-an-app.png) +1. На странице приложения **Обзор** найдите значение **Идентификатор приложения (клиент)** и запишите его, чтобы использовать позже. Вам потребуется это значение, чтобы настроить файл конфигурации Visual Studio для данного проекта. +![Идентификатор приложения](readme-images/aad-application-id.PNG) +1. В списке страниц приложения выберите **Проверка подлинности**. + 1. В разделе **URI перенаправления** выберите параметр **Веб** в поле со списком и введите указанные URI перенаправления. + - `https://mysigninurl` + ![переадресации URI](readme-images/aad-redirect-uri.PNG) +1. Нажмите кнопку **Сохранить**. +1. На странице **Сертификаты и секреты** в разделе **Секреты клиента** выберите **Новый секрет клиента**. + 1. Введите описание ключа (например, `секрет приложения`). + 1. Выберите, когда истекает срок действия ключа: **Через один год**, **Через два года** или **Никогда**. + ![Секрет клиента](readme-images/aad-new-client-secret.png) + 1. После нажатия на кнопку **Добавить** отобразится значение ключа. Скопируйте значение ключа и сохраните его в безопасном месте. + ![Секрет клиента](readme-images/aad-copy-client-secret.png) + Этот ключ понадобится вам позже для настройки проекта в Visual Studio. Это значение ключа больше не будет отображаться и его невозможно получить каким-либо другим способом, поэтому запишите его, как только оно появится на портале Microsoft Azure. + + +1. В списке страниц приложения выберите **Разрешения API**. + 1. Нажмите кнопку **Добавить разрешение** и убедитесь, что выбрана вкладка **Microsoft APIs**. + 1. В разделе **Часто используемые интерфейсы Microsoft API** выберите **Microsoft Graph** + 1. В разделе **Разрешения приложения** убедитесь, что разрешение **Directory.Read.All** проверено. При необходимости используйте поле поиска. + 1. Нажмите кнопку **Добавить разрешения**. + +1. На странице **управление**ми выберите **разрешения API** > **добавьте разрешения**. + + ![Снимок экрана: выбор разрешений API](readme-images/aad-api-permissions.PNG) + +1. Выберите **Microsoft API** > **Microsoft Graph**. + + ![Снимок экрана: разрешения API запроса](readme-images/aad-request-api-permissions.PNG) + +1. Выберите **разрешения приложений**. В поле поиска введите **directory.read.all** и выберите первый вариант из списка. Выберите **Добавить разрешения**. + + ![Скриншот делегированных разрешений](readme-images/aad-application-permissions.PNG) + + +## Настройте функцию Azure +Чтобы создать подписку и получать уведомления от Microsoft Graph, нужно предоставить открытую конечную точку HTTPS. Вы можете использовать функции Azure для того же. + +1. Войдите на [портал Azure](https://portal.azure.com/), используя свою рабочую или учебную учетную запись. + +2. Выберите **Function Apps** в левой области навигации. + +3. Следуйте инструкциям, чтобы создать новое **Function App** + +4. Создать новую функцию **WebHook/API** с помощью приведенного ниже примера кода + +```csharp +using System.Net; + +public static async Task Run(HttpRequestMessage req, ICollector queue, TraceWriter log) +{ + log.Info("C# HTTP trigger function processed a request."); + + // parse query parameter + string validationToken = req.GetQueryNameValuePairs() + .FirstOrDefault(q => string.Compare(q.Key, "validationToken", true) == 0) + .Value; + + log.Info("validationToken: " + validationToken); + + // Get request body + string data = await req.Content.ReadAsStringAsync(); + + log.Info("Body of request: " + data); + + queue.Add(data); + + log.Info("Added message to queue"); + + return string.IsNullOrWhiteSpace(validationToken) + ? req.CreateResponse(HttpStatusCode.Accepted, "Notification received") + : req.CreateResponse(HttpStatusCode.OK, validationToken); +} +``` + +5. Выберите **Интегрировать** > **новый вывод** > **хранилища Azure Queue**. + +6. Введите `очередь` как **имя параметра сообщения** + +7. Введите `webhooksnotificationqueue,` как имя для **очереди** + +8. Использовать существующее или создать новое **подключение учетной записи хранения** + +9. Выберите созданную функцию и **запустите** на портале, чтобы убедиться в ее успешности. + +10. Выберите **Получить функцию URL**, чтобы скопировать URL-адрес уведомления, который будет использоваться в примере. + +## Настройка примера проекта + +1. В обозревателе решений выберите проект **App.config** + + а. Для ключа **clientId** замените *ENTER_YOUR_APP_ID* идентификатором вашего зарегистрированного приложения Azure. + + б. Для ключа **clientSecret** замените *ENTER_YOUR_SECRET* ключом вашего зарегистрированного приложения Azure. + + в. Для ключа **tenantId**замените *ENTER_YOUR_ORGANIZATION_ID* идентификатором вашей организации. + + г. Для ключа **webjobs** замените *ENTER_YOUR_AZURE_STORAGE_CONNECTION_STRING* строкой подключения хранилища Azure, интегрированной в функцию Azure. + + e. Для ключа **notificationurl** замените *ENTER_YOUR_NOTIFICATION_URL* URL-адресом функции Azure. + +## Используйте образец приложения +1. Нажмите клавишу **F5**, чтобы начать ваш образец. + +2. Подождите, пока образец напечатает сообщение. **Создана новая подписка с идентификатором:** + +3. Обновите любое свойство любого пользователя в организации. Пример: Обновить свой номер телефона + +4. Через несколько минут образец должен получить уведомление для обновленного пользователя вместе с его идентификацией. + +5. Каждые 30 секунд образец будет продлевать подписку. Можно изменить период времени обновленной операции, чтобы быть один раз каждые 24 часа. + +## Ключевые компоненты примера + +**Controllers** +-[`Function.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/Functions.cs) Управляет подписками и получает уведомления. +-[`Program.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/SubscriptionController.cs). Начальная загрузка хоста Azure WebJob. + +## Устранение неполадок + +| Выпуск | Разрешение | +| ------ | ------ | +| Вы получаете 403 Запрещенный ответ, когда вы пытаетесь создать подписку. | Убедитесь, что регистрация вашего приложения включает в себя разрешение на **чтение данных каталога данных** для Microsoft Graph (как описано в разделе [Регистрация приложения](#register-the-app)). | +| Вы не получаете уведомления. | Проверьте журналы для функции Azure на [портале](https://portal.azure.com/). Если приложение Microsoft Graph не отправляет уведомления, откройте [Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph), вопрос с пометкой *[MicrosoftGraph]*. Включите идентификатор подписки и время ее создания.

| +| Вы получили *ответ на запрос проверки подписки с истекшим сроком ожидания*. | Это указывает на то, что Microsoft Graph не получил ответ проверки в течение ожидаемого периода времени (около 10 секунд).

Если вы создали функцию Azure в **плане потребления**, то функция может перейти в спящий режим из-за неактивности. Образец попытается снова и должен преуспеть в следующих попытках. Или попробуйте создать функцию Azure, используя план обслуживания приложения. | +| При установке пакетов возникают ошибки. | Убедитесь, что локальный путь к решению не слишком длинный/глубокий. Перемещение решения ближе к корневому диску решает эту проблему. | + + +## Участие ## + +Если вы хотите добавить код в этот пример, просмотрите статью [CONTRIBUTING.MD](/CONTRIBUTING.md). + +Этот проект соответствует [Правилам поведения разработчиков открытого кода Майкрософт](https://opensource.microsoft.com/codeofconduct/). Дополнительные сведения см. в разделе [часто задаваемых вопросов о правилах поведения](https://opensource.microsoft.com/codeofconduct/faq/). Если у вас возникли вопросы или замечания, напишите нам по адресу [opencode@microsoft.com](mailto:opencode@microsoft.com). + +## Вопросы и комментарии + +Мы хотели бы получить ваши отзывы о образце Microsoft Graph Webhooks с помощью WebJobs SDK. Вы можете отправлять нам вопросы и предложения в разделе [Проблемы](https://github.com/microsoftgraph/webjobs-webhooks-sample/issues) этого репозитория. + +Общие вопросы о Microsoft Graph следует задавать на сайте [Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph). Убедитесь, что ваши вопросы или комментарии содержат метку *[MicrosoftGraph]*. + +Если у вас есть предложение по функции, пожалуйста, опубликуйте свою идею на нашей странице [Голос пользователя](https://officespdev.uservoice.com/) и проголосуйте за ваши предложения. + +## Дополнительные ресурсы + +* [Пример веб-перехватчиков Microsoft Graph для Node.js](https://github.com/microsoftgraph/nodejs-webhooks-rest-sample) +* [Работа с веб-перехватчиками в Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) +* [Ресурс подписки](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/subscription) +* [Сайт разработчика Microsoft Graph](https://developer.microsoft.com/en-us/graph/) +* [Вызов Microsoft Graph в приложении ASP.NET MVC](https://developer.microsoft.com/en-us/graph/docs/platform/aspnetmvc) + +© Корпорация Майкрософт (Microsoft Corporation), 2019. Все права защищены. diff --git a/README-localized/README-zh-cn.md b/README-localized/README-zh-cn.md new file mode 100644 index 0000000..9856361 --- /dev/null +++ b/README-localized/README-zh-cn.md @@ -0,0 +1,220 @@ +--- +page_type: sample +description: "此 Azure WebJobs 示例演示了如何开始从 Microsoft Graph 获取通知。" +products: +- ms-graph +languages: +- csharp +extensions: + contentType: samples + technologies: + - Microsoft Graph + services: + - Users + createdDate: 5/10/2017 5:24:11 PM +--- + +# 使用 WebJobs SDK 的 Microsoft Graph Webhook 示例 +订阅 [Microsoft Graph Webhook](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks)，在用户数据更改时获得通知，以便无需轮询更改。 + +此 Azure WebJobs 示例演示了如何开始从 Microsoft Graph 获取通知。Microsoft Graph 提供一个统一的 API 终结点，用于从 Microsoft 云访问数据。 + +>此示例使用 Azure AD 终结点获取工作或学校帐户的访问令牌。此示例使用仅限应用程序的权限，但委派的权限也应正常发挥作用。 + +下面是应用程序可通过 Webhook 订阅执行的常见任务： + +- 获得订阅用户资源的许可，然后获取访问令牌。 +- 使用访问令牌为资源[创建订阅](https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/subscription_post_subscriptions)。 +- 回发验证令牌以确认通知 URL。 +- 收听来自 Microsoft Graph 的通知并使用 202 状态代码进行响应。 +- 请求与使用通知中的数据更改的资源相关的更多信息。 + +应用通过仅限应用的身份验证令牌创建订阅之后，当用户数据中发生事件时，Microsoft Graph 将向注册的通知终结点发送通知。应用随后会对事件作出回应。 + +此示例会订阅`用户`订阅来了解`已更新`和`已删除`更改。该示例假定通知 URL 是 [Azure 函数](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview)，它会侦听 http 上的 Webhook 并立即将这些通知添加到 Azure 存储队列中。该示例使用 [Azure WebJobs SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) 以绑定到 Azure 存储队列，并在 Azure 函数对新通知进行排队时接收这些通知。 + +## 先决条件 + +要通过 WebJobs SDK 使用 Microsoft Graph Webhook 示例，需执行以下操作： + +* 在开发计算机上安装 Visual Studio 2017。 + +* 一个[工作或学校帐户](http://dev.office.com/devprogram)。 + +* [在 Azure 门户中注册](#register-the-app)的应用程序的 ID 和密钥。 + +* 用于接收和发送 HTTP 请求的公共 HTTPS 终结点。你可在 Microsoft Azure 或其他服务上托管此项。该示例已使用 [Azure 函数](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview)进行了测试 + +* [Azure WebJobs SDK](https://docs.microsoft.com/en-us/azure/app-service-web/websites-dotnet-webjobs-sdk) 将使用的 Azure 存储帐户 + +### 创建应用 + +#### 选择要在其中创建应用的租户 + +1. 使用工作/学校帐户登录 [Azure 门户](https://portal.azure.com)。 +1. 如果你的帐户存在于多个 Azure AD 租户中： + 1. 请从页面右上角的菜单中选择你的个人资料，然后选择“**切换目录**”。 + 1. 将会话更改为要在其中创建应用程序的 Azure AD 租户。 + +#### 注册应用 + +1. 导航到 [Azure 门户 >“应用注册”](https://go.microsoft.com/fwlink/?linkid=2083908)以注册应用。 +![应用程序注册](readme-images/aad-app-registration.PNG) +1. 选择“**新注册**”。 +![应用程序注册](readme-images/aad-new-registration.PNG) +1. 出现“**注册应用程序”页面**后，输入应用的注册信息： + 1. 在“**名称**”部分输入一个有意义的名称，该名称将显示给应用用户。例如：`MyWebApp` + 1. 在“**支持的帐户类型**”部分，选择“**任何组织目录中的帐户和个人 Microsoft 帐户(例如 Skype、Xbox、Outlook.com)**”。 +1. 选择“**注册**”以创建应用。 +![注册应用](readme-images/aad-register-an-app.png) +1. 在应用的“**概述**”页上，查找“**应用程序(客户端) ID**”值，记下它供稍后使用。你将需要此值来为此项目配置 Visual Studio 配置文件。 +![应用程序 ID](readme-images/aad-application-id.PNG) +1. 在应用的页面列表中，选择“**身份验证**”。 + 1. 在“**重定向 URI**”部分中，选择组合框中的“ **Web**”，然后输入以下重定向 URI： + - `https://mysigninurl` + ![重定向 URI](readme-images/aad-redirect-uri.PNG) +1. 选择“**保存**”。 +1. 在“**证书和密钥**”页面的“**客户端密码**”部分中，选择“**新建客户端密码**”。 + 1. 键入密钥说明（例如`应用实例`）。 + 1. 选择密钥持续时间：“**1 年内**”、“**2 年内**”或“**永不过期**”。 + ![客户端密码](readme-images/aad-new-client-secret.png) + 1. 单击“**添加**”按钮时，将显示密钥值。复制密钥值并将其存储在安全的位置。 + ![客户端密码](readme-images/aad-copy-client-secret.png) + 稍后需要此密钥来配置 Visual Studio 中的项目。此密钥值将不再显示，也不可用其他任何方式进行检索，因此请在 Azure 门户中看到此值时立即进行记录。 + + +1. 在应用的页面列表中，选择“**API 权限**”。 + 1. 单击“**添加权限**”按钮，然后确保选中“**Microsoft API**”选项卡。 + 1. 在“**常用 Microsoft API**”部分，选择“**Microsoft Graph**”。 + 1. 在“**应用程序权限**”部分，确保已勾选 **Directory.Read.All**。必要时请使用搜索框。 + 1. 选择“**添加权限**”按钮。 + +1. 在“**管理**”页面中，选择“**API 权限**”>“**添加权限**”。 + + ![“选择 API 权限”屏幕截图](readme-images/aad-api-permissions.PNG) + +1. 选择“**Microsoft API**”>“**Microsoft Graph**”。 + + ![“请求 API 权限”屏幕截图](readme-images/aad-request-api-permissions.PNG) + +1. 选择“**应用程序权限**”。在搜索框中，键入 **directory.read.all**，然后从列表中选择第一个选项。选择“**添加权限**”。 + + ![委派的权限屏幕截图](readme-images/aad-application-permissions.PNG) + + +## 设置 Azure 函数 +你必须公开一个公共 HTTPS 终结点才能创建订阅和接收来自 Microsoft Graph 的通知。可使用 Azure Functions 实现这一目的。 + +1. 使用工作/学校帐户登录 [Azure 门户](https://portal.azure.com/)。 + +2. 在左侧导航窗格中选择“**函数应用**”。 + +3. 按照说明新建一个**函数应用** + +4. 使用以下示例代码新建一个 **WebHook/API** 函数 + +```csharp +using System.Net; + +public static async Task Run(HttpRequestMessage req, ICollector queue, TraceWriter log) +{ + log.Info("C# HTTP trigger function processed a request."); + + // parse query parameter + string validationToken = req.GetQueryNameValuePairs() + .FirstOrDefault(q => string.Compare(q.Key, "validationToken", true) == 0) + .Value; + + log.Info("validationToken: " + validationToken); + + // Get request body + string data = await req.Content.ReadAsStringAsync(); + + log.Info("Body of request: " + data); + + queue.Add(data); + + log.Info("Added message to queue"); + + return string.IsNullOrWhiteSpace(validationToken) + ? req.CreateResponse(HttpStatusCode.Accepted, "Notification received") + : req.CreateResponse(HttpStatusCode.OK, validationToken); +} +``` + +5. 选择“**集成**”>“**新输出**”>“**Azure 查询存储**” + +6. 输入 `queue` 作为 **消息参数名称** + +7. 输入 `webhooksnotificationqueue` 作为**队列名称** + +8. 使用现有**存储帐户连接**或新建一个 + +9. 选择所创建的函数，再从门户中**运行**以确保操作成功。 + +10. 选择**获取函数 URL**，复制要在示例中使用的通知 URL。 + +## 设置示例项目 + +1. 在解决方案资源管理器中，选择 **App.config** 项目。 + + a.对于 **clientId** 键，请将 *ENTER_YOUR_APP_ID* 替换为已注册的 Azure 应用的应用程序 ID。 + + b.对于 **clientSecret** 键，请将 *ENTER_YOUR_SECRET* 替换为已注册的 Azure 应用程序的密钥。 + + c.对于 **tenantId** 键，请将 *ENTER_YOUR_ORGANIZATION_ID* 替换为你的组织的 ID。 + + d.对于 **webjobs** 键，请将 *ENTER_YOUR_AZURE_STORAGE_CONNECTION_STRING* 替换为 Azure 函数中集成的 Azure 存储的连接字符串。 + + e.对于 **notificationurl** 键，请将 *ENTER_YOUR_NOTIFICATION_URL* 替换为 Azure 函数的 URL。 + +## 使用示例应用 +1. 按 **F5** 启动示例。 + +2. 等待示例打印“**已使用以下 ID 创建新的订阅:**”消息 + +3. 更新组织中所有用户的所有属性。示例：更新其电话号码 + +4. 几分钟后，示例应会收到有关更新的用户及其标识的通知。 + +5. 示例每 30 秒续订订阅一次。可将已更新操作的时间段更新为每 24 小时一次。 + +## 示例主要组件 + +**控制器** +- [`Function.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/Functions.cs)：管理订阅和接收通知。 +- [`Program.cs`](https://github.com/microsoftgraph/webjobs-webhooks-sample/blob/master/WebHooksSample/SubscriptionController.cs) 启动 Azure WebJob 主机。 + +## 疑难解答 + +| 问题 | 解决方案 | +|:------|:------| +| 你在尝试创建订阅时获得 403 禁用响应。 | 请确保你的应用注册包含对 Microsoft Graph 的**读取目录数据**应用程序权限（如[注册应用](#register-the-app)部分中所述）。 | +| 你没有收到通知。 | 请在[门户](https://portal.azure.com/)中查看 Azure 函数的日志。如果 Microsoft Graph 没有发送通知，请打开标有 *[MicrosoftGraph]* 的 [Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph) 问题。包含订阅 ID 及其创建时间。

| +| 你收到*订阅验证请求超时*响应。 | 此表示 Microsoft Graph 未在预期时间范围内（约 10 秒）收到验证响应。

如果你在**消耗计划**中创建了 Azure 函数，则该函数可能会因为不活动而进入睡眠状态。示例将再次尝试，在后面的尝试中应该会成功。或者，请尝试通过应用服务计划创建 Azure 函数。 | +| 你在安装包时出错。 | 请确保你放置解决方案的本地路径不太长/太深。要解决此问题，可将解决方案移到更接近根驱动器的位置。 | + + +## 参与 ## + +如果想要参与本示例，请参阅 [CONTRIBUTING.MD](/CONTRIBUTING.md)。 + +此项目已采用 [Microsoft 开放源代码行为准则](https://opensource.microsoft.com/codeofconduct/)。有关详细信息，请参阅[行为准则 FAQ](https://opensource.microsoft.com/codeofconduct/faq/)。如有其他任何问题或意见，也可联系 [opencode@microsoft.com](mailto:opencode@microsoft.com)。 + +## 问题和意见 + +我们乐于收到反馈，了解使用 WebJobs SDK 的 Microsoft Graph Webhook 示例的情况。你可通过该存储库中的[问题](https://github.com/microsoftgraph/webjobs-webhooks-sample/issues)部分向我们发送问题和建议。 + +与 Microsoft Graph 相关的一般问题应发布到 [Stack Overflow](https://stackoverflow.com/questions/tagged/MicrosoftGraph)。请确保你的问题或意见标记有 *[MicrosoftGraph]*。 + +如果有功能建议，请将你的想法发布在我们的 [User Voice](https://officespdev.uservoice.com/) 页上，并为你的建议进行投票。 + +## 其他资源 + +* [Microsoft Graph Node.js Webhook 示例](https://github.com/microsoftgraph/nodejs-webhooks-rest-sample) +* [在 Microsoft Graph 中使用 Webhooks](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/webhooks) +* [订阅资源](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/subscription) +* [Microsoft Graph 开发人员网站](https://developer.microsoft.com/en-us/graph/) +* [在 ASP.NET MVC 应用中调用 Microsoft Graph](https://developer.microsoft.com/en-us/graph/docs/platform/aspnetmvc) + +版权所有 (c) 2019 Microsoft Corporation。保留所有权利。